Skunkware 5/Skunkware 5.iso/man/cat.1/xv.1

Text File | 1995-07-25 | 175KB | 3,631 lines

     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



     NNNNAAAAMMMMEEEE
          xxxxvvvv - interactive image display for the X Window System

     SSSSYYYYNNNNTTTTAAAAXXXX
          xxxxvvvv [_o_p_t_i_o_n_s] [_f_i_l_e_n_a_m_e [_f_i_l_e_n_a_m_e...]]

     NNNNOOOOTTTTEEEE
          This man page is merely the text portion of the (PostScript)
          _x_v docs, without the figures, and without the appendicies.
          As such, it is highly recommended that you get your hands on
          the *real* documentation.

     DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
          _x_v is an X11 program that displays images in the GIF, JPEG,
          TIFF, PBM, PGM, PPM, X11 bitmap, Utah Raster Toolkit RLE,
          PDS/VICAR, Sun Rasterfile, and PM formats on 1-, 2-, 4-, 6-,
          8-, 16-, 24-, and 32-bit X displays.  _x_v will also read
          _c_o_m_p_r_e_s_s-ed versions of these files.


     SSSSEEEECCCCTTTTIIIIOOOONNNN 1111:::: OOOOVVVVEEEERRRRVVVVIIIIEEEEWWWW
          _x_v version 2.10 lets you do a large number of things (many
          of them actually useful), including, but not limited to, the
          following:

          o+  display an image in a window on the screen

          o+  display an image on the root window, in a variety of
             styles

          o+  grab any rectangular portion of the screen and turn it
             into an image

          o+  arbitrarily stretch or compress the image

          o+  rotate the image in 90-degree steps

          o+  flip the image around the horizontal or vertical axes

          o+  crop a rectangular portion of the image

          o+  magnify any portion of the image by any amount, up to the
             size of the screen

          o+  determine pixel values and x,y coordinates in the image

          o+  adjust image brightness and contrast with a gamma
             correction function

          o+  apply different gamma functions to the Red, Green, and
             Blue color components, to correct for non-linear color
             response



     Page 1                                          (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          o+  adjust global image saturation

          o+  perform global hue remapping

          o+  perform histogram equalization

          o+  edit an image's colormap

          o+  reduce the number of colors in an image

          o+  dither in color and b&w

          o+  smooth an image

          o+  crop off solid borders automatically

          o+  convert image formats

          o+  generate Encapsulated PostScript

          Unfortunately the _A_u_t_o_m_a_t_i_c _C_h_e_c_k_b_o_o_k _B_a_l_a_n_c_i_n_g _M_o_d_u_l_e still
          isn't completely debugged, and is not included in this
          distribution.


     SSSSEEEECCCCTTTTIIIIOOOONNNN 2222:::: SSSSTTTTAAAARRRRTTTTIIIINNNNGGGG XXXXVVVV
          Note: unless explicitly stated otherwise, the term _c_l_i_c_k
          means "click with the _L_e_f_t mouse button."

          Start the program up by typing 'xv'.  After a short delay, a
          window will appear with the default image (the _x_v logo,
          credits and revision date) displayed in it.  If you change
          the size of the window (using whatever method your window
          manager provides), the image will be automatically stretched
          to fit the window.


        SSSSeeeeccccttttiiiioooonnnn 2222....1111:::: DDDDiiiissssppppllllaaaayyyyiiiinnnngggg PPPPiiiixxxxeeeellll VVVVaaaalllluuuueeeessss
          Clicking (and optionally dragging) the _L_e_f_t mouse button
          inside this window will display pixel information in the
          following format:

               196, 137 = 191,121,209 (287 42 81 HSV)

          The first pair of numbers (196,137) are the x and y
          positions of the cursor, in image coordinates.  These
          numbers remain the same regardless of any image resizing, or
          cropping.  For example, if you click on the eye of the fish
          on the right side of the default image, you'll get
          (approximately) 251,129 regardless of the size of the
          displayed image.  This allows you to zoom in for precise
          measurements.



     Page 2                                          (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          The first triplet of numbers (191,121,209) are the RGB
          values of the selected pixel.  The components will have
          integer values in the range 0-255.  The values displayed are
          prior to any HSV/RGB modification, but after any colormap
          changes.  See "Section 5: The Color Editor" for details.

          The second triplet of numbers (287 42 81) are the HSV values
          of the selected pixel.  The first component will have
          integer values in the range 0-359, and the second and third
          components will have integer values in the range 0-100.  The
          values displayed are prior to any HSV/RGB modification, but
          after any colormap changes.  See "Section 5: The Color
          Editor" for details.  Also, see "Appendix D: RGB and HSV
          Colorspaces" for more information about what these numbers
          mean.

          Note: If you actually want to measure some pixels, it will
          probably help to crop to a small region of your image, and
          expand that region to the point where you can see the
          individual pixels.

          This string is automatically copied to your X server's cut
          buffer whenever you measure pixel values.  This lets you
          easily feed this information to another program, useful if
          you're doing manual feature extraction, or something.  Try
          it: measure a pixel's value, and then go click your _M_i_d_d_l_e
          mouse button in an _x_t_e_r_m window.


        SSSSeeeeccccttttiiiioooonnnn 2222....2222:::: CCCCrrrrooooppppppppiiiinnnngggg
          Bring up the _x_v _c_o_n_t_r_o_l_s window by typing the '?' key or
          clicking the _R_i_g_h_t mouse button inside the image window.

          Clicking and dragging the _M_i_d_d_l_e button of the mouse inside
          the image window will allow you to draw a cropping rectangle
          on the image.  If you're unhappy with the one you've drawn,
          simply click the _M_i_d_d_l_e button and draw another.  If you'd
          like the rectangle to go away altogether, click the _M_i_d_d_l_e
          button and release it without moving the mouse.

          You can determine how large the cropping rectangle is (in
          image coordinates) by bringing up the _x_v _i_n_f_o window.  Do
          this by clicking the IIIInnnnffffoooo button in the _x_v _c_o_n_t_r_o_l_s _w_i_n_d_o_w
          or by typing the 'i' key into any open _x_v window.

          The _x_v _i_n_f_o _w_i_n_d_o_w will display, among other things, the
          current size and position of the cropping rectangle in terms
          of image coordinates.  For example, if it says:

               114x77 rectangle starting at 119,58

          that would mean that the current cropping rectangle is 114



     Page 3                                          (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          image pixels wide, 77 image pixels high, and its top-left
          corner is located 119 image pixels in from the left edge of
          the image, and 58 image pixels in from the top edge.  These
          values will be updated as you drag the cropping rectangle
          around.

          If you want to set the size or position of the cropping
          rectangle precisely, you can use the arrow keys on your
          keyboard.  First, make the _x_v _i_n_f_o window visible as
          described above (if it's not already visible).  Second, use
          the mouse to draw a rough approximation of the cropping
          rectangle that you want.  You can now use the arrow keys to
          move the cropping rectangle around the image.  Once you've
          gotten the top and left sides of the cropping rectangle
          precisely where you want them, you can move the bottom-right
          corner of the cropping rectangle (only) by holding the
          <shift> key down while using the arrow keys.  Pressing the
          up arrow will make the rectangle shorter, and pressing the
          down arrow will make the rectangle taller.

          Once you have a cropping rectangle that you can live with,
          you can proceed with the actual cropping operation.  Click
          the CCCCrrrroooopppp button in the _x_v _c_o_n_t_r_o_l_s window, or type the 'c'
          key in any open _x_v window.  The image window will shrink to
          show only portions of the image that were inside the
          cropping rectangle.

          Note: if you are running a window manager such as _m_w_m, which
          decorates windows with a title bar, resizing regions, and
          such, it is quite possible that the aspect ratio of the
          cropped image will get screwed up.  This is because certain
          window managers enforce a minimum window size.  If you try
          to crop to a rectangle that is too small, the window manager
          will create the smallest window it can, and the image will
          be stretched to fit this window.  If this happens, you can
          press the AAAAssssppppeeeecccctttt button in the _x_v _c_o_n_t_r_o_l_s window, or type
          the 'a' key in any open _x_v window.  This will expand the
          image so that it has the correct aspect ratio again.

          You can crop a cropped image by repeating the same steps
          (drawing a new cropping rectangle and issuing the CCCCrrrroooopppp
          command), ad infinitum.

          You can return to the original, uncropped image by using the
          UUUUnnnnCCCCrrrroooopppp command.  Simply click the UUUUnnnnCCCCrrrroooopppp button or type the
          'u' key in any open _x_v window.  Note that using the UUUUnnnnCCCCrrrroooopppp
          command will turn off image smoothing (the SSSSmmmmooooooootttthhhh) command),
          due to the potentially long time it can take to generate a
          large, smoothed image.

          Note that if you try to make the cropping rectangle too
          small in either width or height (under 5 screen pixels),



     Page 4                                          (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          it'll just turn itself off.  If you want to crop a very
          small portion of an image, you'll probably have to do it in
          two passes.  First, crop to a small (but large enough to
          still be enabled) rectangle, expand that region, then crop
          again.


        SSSSeeeeccccttttiiiioooonnnn 2222....3333:::: ZZZZoooooooommmmiiiinnnngggg
          You can zoom in by a factor of two (or four, eight, etc.) on
          any rectangular region of the image by holding down the
          <ctrl> key on your keyboard and clicking the _L_e_f_t mouse
          button in the image.  A rectangle will flash, centered
          around the cursor position, and the region inside that
          rectangle will be doubled in size.  The image window should
          remain the same size, and in the same position.  You can
          repeat this operation to zoom in by a factor of four, or
          eight, or whatever, as many times as you wish.

          You can zoom out by a factor of two (if possible) by holding
          down the <ctrl> key on your keyboard and clicking the _R_i_g_h_t
          mouse button inside the image window.  You can not zoom out
          beyond the point where the entire image fill the window.


     SSSSEEEECCCCTTTTIIIIOOOONNNN 3333::::     TTTTHHHHEEEE CCCCOOOONNNNTTTTRRRROOOOLLLL WWWWIIIINNNNDDDDOOOOWWWW
          The _x_v _c_o_n_t_r_o_l_s window is the central point of control for
          the program, hence the name.  It provides controls to resize
          the current image, flip and rotate it, load and save
          different files, and bring up the other _x_v windows.  It can
          be brought up by clicking the _R_i_g_h_t mouse button in the
          image window, or by typing the '?' key inside any open _x_v
          window.  Doing either of these things while the _x_v _c_o_n_t_r_o_l_s
          window is visible will hide it.

          All of the following commands may be executed by either
          clicking the appropriate command button, or typing the
          keyboard equivalent (where given) into any open _x_v window.


        SSSSeeeeccccttttiiiioooonnnn 3333....1111:::: RRRReeeessssiiiizzzziiiinnnngggg CCCCoooommmmmmmmaaaannnnddddssss
          Note that none of the 'resizing' commands modify the image
          in any way.  They only affect how the image is displayed.
          The image remains at its original size.  This allows you to
          arbitrarily stretch and compact the image without
          compounding error caused by earlier resizing.  In each case,
          the displayed image is recomputed from the original internal
          image.


          NNNNoooorrrrmmmmaaaallll  (Keyboard equivalent 'n')
               Attempts to return the image to its normal size, where
               one image pixel maps to one screen pixel.  For example,



     Page 5                                          (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



               if the image (or the current cropped portion of the
               image) has a size of 320x200, this command will attempt
               to make the image window be 320 screen pixels wide by
               200 screen pixels high.

               This command may fail in two cases.  If you're running
               a window manager (such as _m_w_m) that enforces a minimum
               window size, and the 'normal' size is too small, the
               image may get distorted.  See the note in "Section 2.2:
               Cropping" for more information.

               Also, if the image is larger than the size of your
               screen, it will be 'halved' until it fits on the
               screen.  For example, if you try to display a 1400x900
               image on a 1280x1024 screen, the NNNNoooorrrrmmmmaaaallll command will
               display a 700x450 image.


          MMMMaaaaxxxx SSSSiiiizzzzeeee  (Keyboard equivalent 'm')
               This command will make the displayed image be the same
               size as the screen.  If you are running a window
               manager that puts up a titlebar, you'll find that the
               titlebar is now off the top of the screen.  To get the
               titlebar back, simply shrink the image to anything
               smaller than the size of the screen.  The window will
               be moved so that the titlebar is once again visible.


          MMMMaaaaxxxxppppeeeecccctttt  (Keyboard equivalent 'M')
               Makes the image as large as possible, while preserving
               the aspect ratio.  This avoids the generally unwanted
               image distortion that MMMMaaaaxxxx SSSSiiiizzzzeeee is capable of
               generating.  For example, if you have a 320x200 image,
               and an 1280x1024 screen, doing the MMMMaaaaxxxxppppeeeecccctttt command will
               result in an image that is 1280x800.  MMMMaaaaxxxx SSSSiiiizzzzeeee, on the
               other hand, would've generated an image of size
               1280x1024, which would be appear 'stretched'
               vertically.


          DDDDbbbbllll SSSSiiiizzzzeeee  (Keyboard equivalent '>')
               Doubles the current size of the image, with the
               constraint that neither axis is allowed to be larger
               than the screen.  For example, given a 320x200 image
               and a 1280x1024 screen, the image can be doubled once
               (to 640x400), a second time (to 1280x800), but a third
               time would make the image 1280x1024.  You'll note that
               on the third time, the width didn't change at all,
               since it was already at its maximum value.  Also note
               that the height wasn't allowed to double (from 800 to
               1600), but was truncated at its maximum value (1024).




     Page 6                                          (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          HHHHaaaallllffff SSSSiiiizzzzeeee  (Keyboard equivalent '<')
               Halves the current size of the image, with the
               constraint that neither axis is allowed to have a size
               less than 1 pixel.  Also, you may run into 'minimum
               size' problems with your window manager.  See the note
               in "Section 2.2: Cropping" for more information.

               Note that the window size is maintained as a pair of
               integers.  As a result you may see some integer round-
               off problems.  For example, if you halve a 265x185
               image, you'll get a 132x92 image, which is just fine.
               However, if you DDDDbbbbllll SSSSiiiizzzzeeee this image, you'll get a
               264x184 image, not the 265x185 image you might have
               expected.


          ++++11110000%%%%  (Keyboard equivalent '.')
               Increases the current size of the image by 10%, subject
               to the constraint that the image cannot be made larger
               than the screen size (in either axis).  For example,
               issuing this command on a 320x200 image will result in
               a 352x220 image.


          ----11110000%%%%  (Keyboard equivalent ',')
               Decreases the current size of the image by 10%.
               Neither axis of the image is allowed to shrink below 1
               pixel.  Also, you run the risk of running into 'minimum
               window size' problems with your window manager.

               It should be noted that the ++++11110000%%%% and ----11110000%%%% commands have
               no concept of an 'original size'.  They simply increase
               or decrease the current image size by 10%.  As a
               result, they do not undo each other.  For example, take
               a 320x200 image.  Do a ++++11110000%%%% and the image will be
               352x220.  If you issue the ----11110000%%%% command now, the image
               will be made (352 - 35.2)x(220 - 22), or 316x198.


          4444xxxx3333  (Keyboard equivalent '4')
               Attempts to resize the image so that the ratio of width
               to height is equal to 4 to 3.  (e.g., 320x240, 400x300,
               etc.)  This is useful because many images were meant to
               fill the screen of whatever system they were generated
               on, and nearly all video tubes have an aspect ratio of
               4:3.  This command will stretch the image so that
               things will probably look right on your X display
               (nearly all of which, thankfully, have square pixels).
               This command is particularly useful for images which
               have really bizarre sizes (such as the 600x200 images
               presumably meant for CGA, and the 640x350 16-color EGA
               images).



     Page 7                                          (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          AAAAssssppppeeeecccctttt  (Keyboard equivalent 'a')
               Applies the 'default aspect ratio' to the image.  This
               is done automatically when the image is first loaded.
               Normally, the default aspect ratio is '1:1', but
               certain GIF files may have an aspect ratio encoded in
               them.  You can also set the default aspect ratio via a
               command-line argument or an X resource.  See 'Section
               9: Modifying XV Behavior' for more info.  The idea
               behind this command is that you'd stretch the image
               manually (via your window manager) to roughly the size
               you'd like, and then use the Aspect command to fix up
               the proportions.

               Normally AAAAssssppppeeeecccctttt expands one axis of the image to
               correct the aspect ratio.  If this would result in an
               image that is larger than the screen, the AAAAssssppppeeeecccctttt
               command will instead shrink one of the axes to correct
               the aspect ratio.


        SSSSeeeeccccttttiiiioooonnnn 3333....2222:::: RRRRoooottttaaaatttteeee////FFFFlllliiiipppp CCCCoooommmmmmmmaaaannnnddddssss
          TTTTuuuurrrrnnnn CCCCWWWW  (Keyboard equivalent 't')
               Rotates the image 90 degrees clockwise.


          TTTTuuuurrrrnnnn CCCCCCCCWWWW  (Keyboard equivalent 'T')
               Rotates the image 90 degrees counter-clockwise.


          FFFFlllliiiipppp HHHH  (Keyboard equivalent 'h')
               Flips the image horizontally (around the vertical
               center-line of the image).


          FFFFlllliiiipppp VVVV  (Keyboard equivalent 'v')
               Flips the image vertically (around the horizontal
               center-line of the image).


        SSSSeeeeccccttttiiiioooonnnn 3333....3333:::: SSSSmmmmooooooootttthhhhiiiinnnngggg CCCCoooommmmmmmmaaaannnnddddssss
          RRRRaaaawwww  (Keyboard equivalent 'r')
               Returns the displayed image to its 'raw' state (where
               each pixel in the displayed image is as close as
               possible to the corresponding pixel in the internal
               image).  In short, it turns off any dithering or
               smoothing.  When dithering or smoothing haven't been
               done, this command is disabled.


          DDDDiiiitttthhhheeeerrrr  (Keyboard equivalent 'd')
               Regenerates the displayed image by dithering with the
               available colors in an attempt to approximate the



     Page 8                                          (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



               original image.  This is only relevant if the color
               allocation code failed to get all the colors it wanted.
               If it did get all the desired colors, the DDDDiiiitttthhhheeeerrrr
               command will just generate the same display image as
               the RRRRaaaawwww command.  On the other hand, if you didn't get
               all the desired colors, the DDDDiiiitttthhhheeeerrrr command will try to
               approximate the missing colors by dithering with the
               colors that were obtained.  If you're running _x_v on a
               1-bit display the DDDDiiiitttthhhheeeerrrr command will be disabled, as
               the image will always be dithered for display.


          SSSSmmmmooooooootttthhhh  (Keyboard equivalent 's')
               Smooths out distortion caused by integer round-off when
               an image is expanded or shrunk.  This is generally a
               desirable effect, however it is fairly time-consuming
               on large images on most current workstations.  As such,
               by default, it is not done automatically.  See "Section
               9: Modifying XV Behavior" for more details.


        SSSSeeeeccccttttiiiioooonnnn 3333....4444:::: CCCCrrrrooooppppppppiiiinnnngggg CCCCoooommmmmmmmaaaannnnddddssss
          CCCCrrrroooopppp  (Keyboard equivalent 'c')
               Crops the image to the current cropping rectangle.
               This command is only available when a cropping
               rectangle has been drawn on the image.  See "Section
               2.2: Cropping" for further information.


          UUUUnnnnCCCCrrrroooopppp  (Keyboard equivalent 'u')
               Returns the image to its normal, uncropped state.  This
               command is only available after the image has been
               cropped.  See "Section 2.2: Cropping" for further
               information.


          AAAAuuuuttttooooCCCCrrrroooopppp  (Keyboard equivalent 'A')
               Crops off any constant borders that exist in the image.
               It will crop to the smallest rectangle that encloses
               the 'interesting' section of the image.  It may not
               always appear to work because of minor invisible color
               changes in the image.  As such, it works best on
               computer-generated images, and not as well on scanned
               images.


        SSSSeeeeccccttttiiiioooonnnn 3333....5555:::: TTTThhhheeee DDDDiiiissssppppllllaaaayyyy MMMMooooddddeeeessss MMMMeeeennnnuuuu
          In addition to displaying an image in a window, _x_v can also
          display images on the root (background) window of your X
          display.  There are a variety of ways that _x_v can display an
          image on the root window.  The DDDDiiiissssppppllllaaaayyyy MMMMooooddddeeeessss popup menu lets
          you select where (and how) _x_v will display the image.



     Page 9                                          (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          Click on the DDDDiiiissssppppllllaaaayyyy MMMMooooddddeeeessss button in the _x_v _c_o_n_t_r_o_l_s window,
          and hold the mouse button down.  This will cause the DDDDiiiissssppppllllaaaayyyy
          MMMMooooddddeeeessss menu to pop up.  The current display mode will be
          shown with a check mark next to it.  To select a new mode,
          drag the mouse down to the desired mode, and release the
          mouse button.

          It is not possible for _x_v to receive button presses or
          keyboard presses in the root window.  As such, there are
          several functions that cannot be used while in a 'root'
          mode, such as pixel tracking and image cropping.  If you
          want to do such things, you'll have to temporarily return to
          'window' mode, and return to 'root' mode when you're
          finished.  Also, when you are in a 'root' mode, you will not
          be able to get rid of the _x_v _c_o_n_t_r_o_l_s window.  At best you
          can iconify it (using your window manager).  (The reason for
          this is that if you ever got rid of it there'd be no way to
          get it back.)


          WWWWiiiinnnnddddoooowwww
               Displays the image in a window.  If you were previously
               in a 'root' mode, the root window will also be cleared.


          RRRRooooooootttt:::: TTTTiiiilllleeeedddd
               The image is displayed in the root window.  One image
               is displayed aligned with the top-left corner of the
               screen.  The image is then duplicated towards the
               bottom and right edges of the screen, as many times as
               necessary to fill the screen.


          RRRRooooooootttt:::: IIIInnnntttteeeeggggeeeerrrr TTTTiiiilllleeeedddd
               Similar to RRRRooooooootttt:::: TTTTiiiilllleeeedddd, except that the image is first
               shrunk so that its width and height are integer
               divisors of the screen's width and height.  This keeps
               the images along the bottom and right edges of the
               screen from being NNNNoooorrrrmmmmaaaallll, DDDDbbbbllll SSSSiiiizzzzeeee, etc.) will lose the
               'integer'-ness of the image.


          RRRRooooooootttt:::: MMMMiiiirrrrrrrroooorrrreeeedddd
               Tiles the original image with versions that have been
               horizontally flipped, vertically flipped, and both
               horizontally and vertically flipped.  This gets rid of
               the sharp dividing lines where tiled images meet.  The
               effect is quite interesting.


          RRRRooooooootttt:::: IIIInnnntttteeeeggggeeeerrrr MMMMiiiirrrrrrrroooorrrreeeedddd
               Like RRRRooooooootttt:::: MMMMiiiirrrrrrrroooorrrreeeedddd, but also does the integer-ization



     Page 10                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



               described under the RRRRooooooootttt:::: IIIInnnntttteeeeggggeeeerrrr TTTTiiiilllleeeedddd entry.


          RRRRooooooootttt:::: CCCCeeeennnntttteeeerrrr TTTTiiiilllleeeedddd
               Like RRRRooooooootttt:::: TTTTiiiilllleeeedddd, but it positions the images so that
               one of them is centered on the screen, and the rest are
               tiled off in all directions.  Visually pleasing without
               the image size distortion associated with RRRRooooooootttt:::: IIIInnnntttteeeeggggeeeerrrr
               TTTTiiiilllleeeedddd.


          RRRRooooooootttt:::: CCCCeeeennnntttteeeerrrreeeedddd
               Displays a single image centered in the root window,
               surrounded by black.


          RRRRooooooootttt:::: CCCCeeeennnntttteeeerrrreeeedddd,,,, WWWWaaaarrrrpppp
               Displays a single image centered in the root window,
               surrounded by a black and white 'warp' pattern, which
               produces some mildly visually pleasing Moire effects.


          RRRRooooooootttt:::: CCCCeeeennnntttteeeerrrreeeedddd,,,, BBBBrrrriiiicccckkkk
               Displays a single image centered in the root window,
               surrounded by a black and white 'brick' pattern.


          Note: The three 'centered' modes (RRRRooooooootttt:::: CCCCeeeennnntttteeeerrrreeeedddd, RRRRooooooootttt::::
          CCCCeeeennnntttteeeerrrreeeedddd,,,, WWWWaaaarrrrpppp, and RRRRooooooootttt:::: CCCCeeeennnntttteeeerrrreeeedddd,,,, BBBBrrrriiiicccckkkk, but not RRRRooooooootttt::::
          CCCCeeeennnntttteeeerrrr TTTTiiiilllleeeedddd) require the creation of a Pixmap the size of
          the screen.  This can be a fairly large request for
          resources, and will fail on a color X terminal with
          insufficient memory.  They can also require the transmission
          of considerably more data than the other 'root' modes.  If
          you're on a brain-damaged X terminal hanging off a slow
          network, you should probably go somewhere else.  Barring
          that, you should certainly avoid the 'centered' modes.

          Also note: If you quit _x_v while displaying an image on the
          root window, the image will remain in the root window, and
          the colors used by the image will remain allocated.  This is
          generally regarded as correct behavior.  If you decide you
          want to get rid of the root image to free up resources, or
          simply because you're sick of seeing it, the quickest route
          is to use run 'xv -clear', which will clear the root window,
          release any allocated colors, and exit.  Alternately,
          _x_s_e_t_r_o_o_t and any other X program that puts things in the
          root window should be able to do the trick as well.


        SSSSeeeeccccttttiiiioooonnnn 3333....6666:::: TTTThhhheeee 22224444----bbbbiiiitttt CCCCoooonnnnvvvveeeerrrrssssiiiioooonnnn MMMMeeeennnnuuuu
          _x_v can currently only operate on 8-bit images.  Whenever you



     Page 11                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          load a 24-bit image (such as JPEG, TIFF, PPM, etc) it is
          immediately converted into an 8-bit colormapped image using
          one of three algorithms.


          FFFFaaaasssstttt Converts 24-bit images into 8-bit images by dithering
               with a fixed 6x6x6 RGB colormap.  It is the quickest of
               the three algorithms, but also generally produces the
               worst images.  It can also be selected via the '-
               quick24' command-line option or X resource.


          SSSSlllloooowwww The default algorithm.  Takes about twice as long as
               the fast algorithm. Uses the median-cut algorithm to
               pick a set of 256 colors, and then dithers using these
               colors.  It can be selected via the '-slow24' command-
               line option or X resource.


          BBBBeeeesssstttt By far and away the slowest of the algorithms.  It can
               take up to ten times as long as the 'slow' algorithm.
               It uses a cleverer version of the median-cut algorithm
               to pick a better set of colors than the slow algorithm.
               It does nnnnooootttt dither.  This might look best if you're
               going to be expanding the image by very much, as the
               dithering in the other two algorithms becomes very
               noticable.  You can also select this option via the '-
               best24' command-line option or X resource.


        SSSSeeeeccccttttiiiioooonnnn 3333....7777:::: WWWWoooorrrrkkkkiiiinnnngggg WWWWiiiitttthhhh MMMMuuuullllttttiiiipppplllleeee FFFFiiiilllleeeessss
          _x_v provides a a set of controls that let you conveniently
          operate on a list of images.  To use the following commands,
          you'll have to start up _x_v with a list of filenames.  For
          example, you could type 'xv *.gif' (assuming, of course,
          that you have a bunch of files that end with the suffix
          '.gif' in the current directory).

          The filenames are listed in a scrollable window.  The
          current selection is shown in reverse video.  If there are
          more names than will fit in the window, the scrollbar will
          be enabled.


        SSSSeeeeccccttttiiiioooonnnn 3333....7777....1111:::: OOOOppppeeeerrrraaaattttiiiinnnngggg aaaa LLLLiiiisssstttt WWWWiiiinnnnddddoooowwww
          The scrollbar operates as follows:

          o+  clicking in the top or bottom arrow of the scrollbar
             scrolls the list by one line in the appropriate
             direction.  It will continue to scroll the list as long
             as you hold the mouse down.




     Page 12                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          o+  The thumb (the small white rectangle in the middle of the
             scrollbar) shows roughly where in the list you are.  You
             can change your position in the list by clicking and
             dragging the thumb to another position in the scrollbar.
             The list will scroll around as you move the thumb.

          o+  You can scroll the list up or down a page at a time by
             clicking in the grey region between the thumb and the top
             or bottom arrows.

          If you click on a name in the list, that name will become
          highlighted.  You can drag the highlight bar up and down,
          and the list will scroll appropriately.

          It is also possible to control the list window from the
          keyboard.  In all cases, you must make sure that the window
          sees the keypress.  Generally, this means you have to have
          the cursor inside the window, though your window manager may
          also require you to click inside the window first.

          o+  The up and down arrow keys move the highlight bar up and
             down.  If the bar is at the top or bottom of the window,
             the list will scroll one line.

          o+  The page up and page down keys scroll the list up or down
             a page at a time.

          o+  Pressing the home key will jump to the beginning of the
             list.  Pressing the end key will jump to the bottom of
             the list.


        SSSSeeeeccccttttiiiioooonnnn 3333....7777....2222:::: TTTThhhheeee FFFFiiiilllleeee CCCCoooommmmmmmmaaaannnnddddssss
          You can directly view any image in the list by double-
          clicking on its filename.  If _x_v is unable to load the file
          (for any of a variety of reasons), it'll display an error
          message and put up the default image, the _x_v logo.


          NNNNeeeexxxxtttt  (Keyboard equivalent <space>)
               Attempts to load the next file in the list.  If it is
               unable to load the next file, it will continue down the
               list until it successfully loads a file.  If it gets to
               the bottom of the list without successfully loading a
               file, it will put up the default image.


          PPPPrrrreeeevvvviiiioooouuuussss  (Keyboard equivalent <backspace>)
               Attempts to load the previous file in the list.  If it
               is unable to load the previous file, it will continue
               up the list until it successfully loads a file.  If it
               gets to the top of the list without successfully



     Page 13                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



               loading a file, it will put up the default image.


          DDDDeeeelllleeeetttteeee  (Keyboard equivalent <ctrl-D>)
               This command lets delete the currently selected file
               from the list (and optionally delete the associated
               disk file).  Note that the currently selected file is
               the one with the highlight bar on it.  While this is
               generally the same as the currently displayed image, it
               doesn't have to be.

               The DDDDeeeelllleeeetttteeee command will pop-up a window asking you what
               you want to delete.  Your choices are:

               o+  LLLLiiiisssstttt EEEEnnnnttttrrrryyyy, which will remove the highlighted name
                  from the list.  (Keyboard equivalent: the enter key)

               o+  DDDDiiiisssskkkk FFFFiiiilllleeee, which will remove the highlighted name
                  from the list and also delete the associated disk
                  file.  This removes unwanted images, just like
                  manually typing 'rm <filename>' in another window.
                  (Keyboard equivalent: <ctrl-D>)

               o+  CCCCaaaannnncccceeeellll, which lets you get out of the Delete command
                  without actually deleting anything.  (Keyboard
                  equivalent: the esc key)

        SSSSeeeeccccttttiiiioooonnnn 3333....7777....3333:::: IIIImmmmaaaaggggeeee RRRReeeellllooooaaaaddddiiiinnnngggg
          It is occasionally desirable to reload an image file because
          the contents of the file have changed.  For example, you
          could be downloading a file, and you might want to keep
          reloading the file to check on the progress of the download.
          Or perhaps you have a program that generates images, and
          you'd like to view these images without any manual
          intervention.

          _X_V provides a way to reload an image via an external signal.
          If you send the xv process a SIGQUIT signal ('kill -QUIT
          _p_i_d', or currently selected file.  (The one that is
          currently highlighted in the _x_v _c_o_n_t_r_o_l_s window filename
          list.)  This behavior is exactly the same as hitting
          '<return>' in the _x_v _c_o_n_t_r_o_l_s window.  If _x_v is currently in
          a state where hitting '<return>' in the controls window
          won't load an image (ie, some pop-up dialog box is grabbing
          all such events), then sending this signal wonUt work
          either.

          An idea: You could write a 'clock' program that, once a
          minute, generates a really spiffy looking picture of the
          current time (with color gradations, 3d extruded numbers,
          whatever), then sends _x_v the signal to reload the generated
          image.



     Page 14                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



        SSSSeeeeccccttttiiiioooonnnn 3333....8888:::: TTTThhhheeee GGGGrrrraaaabbbb CCCCoooommmmmmmmaaaannnndddd
          The GGGGrrrraaaabbbb command works as follows:  click on the GGGGrrrraaaabbbb button
          in the _x_v _c_o_n_t_r_o_l_s window, or type a <ctrl-G> key in any
          active _x_v window (except for the JPEG, PostScript, and TIFF
          'save' dialog boxes).  The terminal will beep once, and the
          cursor will change to a cross.  The screen will remain
          frozen until you complete the GGGGrrrraaaabbbb command.

          You can GGGGrrrraaaabbbb an arbitrary region of the screen by clicking
          the _L_e_f_t mouse button and dragging a rectangle in exactly
          the same way you draw a cropping rectangle.  When you let go
          of the mouse button, the contents of this rectangle will be
          read from the screen and loaded into _x_v.

          Alternately, you can grab the entire contents of a window
          (including its frame) by clicking the _M_i_d_d_l_e mouse button
          anywhere inside the chosen window.  If you click the _M_i_d_d_l_e
          mouse button somewhere on the root window, the entire screen
          will be loaded into _x_v.

          Or, alternately, you can simply abort the GGGGrrrraaaabbbb command by
          clicking the _R_i_g_h_t mouse button anywhere on the screen.

          You can use the GGGGrrrraaaabbbb command for a wide variety of purposes.
          For example, you can use it to print the contents of any
          window (or the whole screen) by grabbing the appropriate
          image and then saving it as a PostScript file.

          You can use the GGGGrrrraaaabbbb command, in conjunction with the Zoom
          and UnZoom commands, as an effective replacement for the
          _x_m_a_g program.

          You can also use the GGGGrrrraaaabbbb command to pick 'just the right
          colors' for any application.  Simply start the application
          in question, GGGGrrrraaaabbbb the window into _x_v, and use the colormap
          editor to twiddle the colors around to your heart's content.

          Note:  The GGGGrrrraaaabbbb command does not work on Macintoshes running
          _M_a_c_X in a rootless mode, which isn't too surprising, if you
          think about it...


        SSSSeeeeccccttttiiiioooonnnn 3333....9999:::: OOOOtttthhhheeeerrrr CCCCoooommmmmmmmaaaannnnddddssss
          IIIInnnnffffoooo  (Keyboard equivalent 'i')
               Opens and closes the _x_v _i_n_f_o window.  See "Section 4:
               The Info Window" for more details.


          CCCCoooollllEEEEddddiiiitttt  (Keyboard equivalent 'e')
               Opens and closes the _x_v _c_o_l_o_r _e_d_i_t_o_r window.  See
               "Section 5: The Color Editor" for more details.




     Page 15                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          LLLLooooaaaadddd  (Keyboard equivalent <ctrl-L>)
               Opens the _x_v _l_o_a_d window.  See "Section 6: The Load
               Window" for more details.


          SSSSaaaavvvveeee  (Keyboard equivalent <ctrl-S>)
               Opens the _x_v _s_a_v_e window.  See "Section 7: The Save
               Window" for more details.


          QQQQuuuuiiiitttt  (Keyboard equivalent 'q')
               Quits out of the program.


     SSSSEEEECCCCTTTTIIIIOOOONNNN 4444::::     TTTTHHHHEEEE IIIINNNNFFFFOOOO WWWWIIIINNNNDDDDOOOOWWWW
        SSSSeeeeccccttttiiiioooonnnn 4444....1111:::: OOOOvvvveeeerrrrvvvviiiieeeewwww
          _x_v provides a window to display information about the
          current image, color allocation, expansion, cropping, and
          any error messages.  This window can be opened by issuing
          the Info command.  (Click on the Info button in the _x_v
          _c_o_n_t_r_o_l_s window, or type 'i' in any open _x_v window.) You can
          close the window by using the IIIInnnnffffoooo command while the window
          is open.  You can also close the window by clicking anywhere
          inside it.

          The top portion of the window displays the program name,
          revision date, and patchlevel.  It also shows the University
          of Pennsylvania shield, the GRASP Lab logo, the copyright
          notice, and of course, the author's name.


        SSSSeeeeccccttttiiiioooonnnn 4444....2222:::: TTTThhhheeee FFFFiiiieeeellllddddssss
          The "Filename" field displays the name of the currently
          loaded file.  The name is displayed without any leading
          pathname.  If there is no currently loaded image (you're
          looking at the default image) this field will display
          "<none>".

          The "Format" field displays information describing what
          image format the file is stored in, and how large the file
          is (in bytes).

          The "Resolution" field shows the width and height (in image
          pixels) of the loaded image.  Note that this does not
          necessarily have anything to do with the size of the image
          currently displayed on your screen.  These numbers do not
          change as you modify the display image.

          The "Cropping" field displays the current state of any
          cropping activity.  If you are looking at the entire
          (uncropped) image, and there is no cropping rectangle drawn,
          this field will show "<none>".  If you draw a cropping



     Page 16                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          rectangle, or if you are viewing cropped portion of image,
          this field will display something like "247x128 rectangle
          starting at 132,421".  See "Section 2.2: Cropping" for more
          details.

          The "Expansion" field gives you information about how the
          image is displayed.  It will display something like "1.58 x
          1.37 (505 x 273)".  This tells you that the current
          displayed image is 505 pixels wide and 273 pixels high, and
          that it is 1.58 times wider and 1.37 times higher than the
          internal image (which, in this case, had a size of 320x200).

          The "Colors" field gives you detailed information on how
          well (or poorly) color allocation went.  If everything went
          reasonably well it will display something like:

               Got all 67 desired colors.  (66 unique)

          This means that 67 entries in the image's colormap were used
          in the image, but that only 66 of these colors were
          different, as far as the X server was concerned.

          See "Appendix E: Color Allocation" for a complete discussion
          of how colors are allocated, and what the "Colors" field can
          tell you.

          Note that the fields are filled in as information becomes
          available.  As such, they can be used as a rough 'progress
          indicator' when loading images.  When you begin loading, all
          the fields are cleared.  Once the image has been
          successfully loaded, the top three fields (Filename, Format,
          Resolution) are filled in.  Once the colors have been
          allocated, and the display image generated, the bottom three
          fields are shown (Cropping, Expansion, and Colors).


        SSSSeeeeccccttttiiiioooonnnn 4444....3333:::: SSSSttttaaaattttuuuussss LLLLiiiinnnneeeessss
          The bottom two lines in the info window display various
          error messages, warnings, and status information.  These two
          lines are also duplicated in the _x_v _c_o_n_t_r_o_l_s window.

          The upper line is the more commonly used.  It normally
          displays a one-line summary of the current image and color
          allocation success.  If an error occurs, it will be
          displayed on this line as well.

          The lower line is used to display warning messages.


     SSSSEEEECCCCTTTTIIIIOOOONNNN 5555::::     TTTTHHHHEEEE CCCCOOOOLLLLOOOORRRR EEEEDDDDIIIITTTTOOOORRRR
        SSSSeeeeccccttttiiiioooonnnn 5555....1111:::: OOOOvvvveeeerrrrvvvviiiieeeewwww
          The _x_v _c_o_l_o_r _e_d_i_t_o_r provides a powerful system for



     Page 17                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          manipulating color images.  Since there are many different
          reasons why a person would want to modify an image's colors,
          and many different types of images that may need
          modification, there is no one color manipulation tool that
          would be 'best' for all purposes.  Because of this problem,
          _x_v gives the user three different color tools, all of which
          can be used simultaneously.

          o+  Colormap Editing: This tool lets you arbitrarily modify
             individual colormap entries.  Useful for modifying the
             color of captions or other things that have been added to
             images.  Also works well on images that have a small
             number of colors, such as images generated by 'drawing'
             or CAD programs.  It's also an easy way to spiff up
             boring 1-bit black and white images.

          o+  HSV Modification: This tool lets you alter the image
             globally in the HSV colorspace.  (See "Appendix D: RGB
             and HSV Colorspaces" for more info.)  Here are examples
             of the sort of things you can do with this tool:

             o+  turn all the blues in an image into reds

             o+  change the tint of an image

             o+  change a greyscale image into a mauve-scale image

             o+  increase or decrease the amount of color saturation in
                an image

             o+  change the overall brightness of an image

             o+  change the overall contrast of an image

          o+  RGB Modification: This tool lets you route the red,
             green, and blue color components of an image through
             independent mapping functions.  The functions can either
             be the standard gamma function, or any arbitrary function
             that can be drawn with straight line segments or a cubic
             spline.  See "Section 5.3.4: The Intensity Graph" for
             more info about graph functions.

          The major use of the RGB Modification tool is to correct for
          the differing color response curves of various color
          monitors, printers, and scanners.  This is the tool to use
          when "the image is too red", for instance.

          These three tools are tied together in a fixed order.  The
          Colormap Editing tool operates on the original colors in the
          image.  The output of this tool is piped into the HSV
          Modification tool.  Its output is piped into the RGB
          Modification tool.  The output from the RGB Modification



     Page 18                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          tool is what actually gets displayed.

          In addition there is a collection of buttons that control
          the _x_v _c_o_l_o_r _e_d_i_t_o_r as a whole (more or less).

          Don't Panic!  It's not as complicated as it looks.


        SSSSeeeeccccttttiiiioooonnnn 5555....2222:::: TTTThhhheeee CCCCoooolllloooorrrrmmmmaaaapppp EEEEddddiiiittttiiiinnnngggg TTTToooooooollll
          The top portion of this window shows the colormap of the
          current image.  There are 16 cells across, and up to 16 rows
          down, for a maximum of 256 color cells.  Only cells actually
          used somewhere in the image are shown in this array.

          The currently selected color cell is shown with a thick
          border.  You can change the selection by clicking anywhere
          in the array.  If you drag the mouse through this area,
          you'll see the dials at the bottom change to track the
          current pixel values.

          You can also select a color cell by clicking anywhere in the
          image window.  Whichever pixel value you were on when you
          let go of the mouse will become the new selected color cell.

          You can define a smoothly gradated range of colors by _L_e_f_t
          clicking on the color cell that marks the 'start' of the
          range, and _M_i_d_d_l_e clicking on the color cell that marks the
          'end' of the range.  Intervening color cells will be
          interpolated between the colors of the

          As an example:

          o+  View the 'default' image by running _x_v without specifying
             any filenames.

          o+  Open the _x_v _c_o_l_o_r _e_d_i_t_o_r window, and _L_e_f_t click on the
             first color cell.

          o+  Turn this color cell _r_e_d by setting the RGB dials to
             255,0,0.

          o+  _L_e_f_t click on the 64th color cell (the rightmost color
             cell in the last complete row).

          o+  Turn this color cell _y_e_l_l_o_w by setting the RGB dials to
             255,255,0.

          o+  _M_i_d_d_l_e click on the first color cell.  A smooth series of
             _y_e_l_l_o_w_i_s_h-_r_e_d_s will be generated from the 64th color cell
             to the first color cell.  Note that the 'direction'
             doesn't matter.




     Page 19                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          Since certain images will have many colors that are the
          same, or nearly the same, it is sometimes convenient to
          group color cells together.  Grouped color cells all take on
          the same color, and changing any one of them affects all of
          the other colors in the group.

          To group color cells together, do the following:

          o+  Hold down the <shift> key.

          o+  Left click on one color cell that you would like to be in
             the group

          o+  Right click on other color cells that you wish to be in
             this group.  (Right clicking on cells that are already
             selected will de-select them.)

          o+  Release the <shift> key when you're done.

          You can create as many groups as you like.

          You can use this grouping/ungrouping technique to copy
          colors from one color cell to another.  Left click on the
          source color cell, Right click on the destination color
          cell, and Right click on the destination color cell again
          (to ungroup it).


        SSSSeeeeccccttttiiiioooonnnn 5555....2222....1111:::: UUUUssssiiiinnnngggg tttthhhheeee DDDDiiiiaaaallll CCCCoooonnnnttttrrrroooollllssss
          At the bottom the Colormap Editing tool are three dials that
          let you set the color of the current color cell (or group of
          cells).  By default, the dials control the Red, Green, and
          Blue components of the RGB colorspace, but they can also
          control the Hue, Saturation, and Value components of the HSV
          colorspace.  (The RRRRGGGGBBBB////HHHHSSSSVVVV button controls this.)

          Regardless of what they control, all dials in _x_v work the
          same way.  Clicking on the single arrows increase/decrease
          the value by 1.  Clicking on the double arrows
          increase/decrease the value by a larger amount (16 in this
          case).  If you click on one of the arrows, and hold the
          mouse button down, the increase/decrease will repeat until
          you release the mouse button.

          You can also click in the general area of the pointer and
          simply drag it to the position you want.  The further your
          mouse cursor is from the center of the dial, the more
          precise the control will be.  While dragging, you do not
          have to keep the cursor inside the dial window.


        SSSSeeeeccccttttiiiioooonnnn 5555....2222....2222:::: CCCCoooolllloooorrrrmmmmaaaapppp EEEEddddiiiittttiiiinnnngggg CCCCoooommmmmmmmaaaannnnddddssss



     PPPPaaaaggggeeee 22220000                                         ((((pppprrrriiiinnnntttteeeedddd 3333////11116666////99994444))))






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          CCCCoooollllUUUUnnnnddddoooo
               Undoes the last change made to the colormap that
               resulted in a color cell changing value.  This includes
               grouping and ungrouping color cells, and changing any
               of the dials.


          RRRReeeevvvveeeerrrrtttt
               Undoes all color changes.  Returns the colormap to its
               original state.  Destroys any groups that you may have
               created.


          RRRRGGGGBBBB////HHHHSSSSVVVV
               Toggles the Colormap Editing dials between editing
               colors in terms of Red, Green, and Blue, and editing
               colors in terms of Hue, Saturation, and Value.


          GGGGrrrreeeeyyyy Turns color images into greyscale images by changing
               the colormap.  This replaces each color cell with a
               greyscale representation of itself.  Use the RRRReeeevvvveeeerrrrtttt
               command to restore the colors.


          RRRReeeevvvvVVVViiiidddd
               This command behaves differently, depending on the
               setting of the RGB/HSV mode.  (You can tell which mode
               you're in by the titles on the dials.)

               In RGB mode, each color component is separately
               'inverted'.  For example, Yellow (which is composed of
               full red, full green, and no blue) would turn to Blue
               (no red, no green, full blue).

               In HSV mode, only the Value (intensity) component is
               'inverted'.  The Hue and Saturation components remain
               the same.  In this mode, bright colors turn to dark
               versions of the same color.  For example, a Yellow
               would turn Brown.


          RRRRaaaannnnddddoooommmm
               Generates a random colormap.  This is of questionable
               usefulness, but it will occasionally come up with
               pleasing color combinations that you never would've
               come up with yourself.  So it stays in.  It works best
               on images with a small number of colors.  Note that it
               respects cell groupings, so if your image has a lot of
               colors, you can create a few large groups and then use
               the Random command.




     Page 21                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          Note: It is HIGHLY RECOMMENDED that if you're using the
          Colormap Editing tool, you do NOT use the HSV Modification
          tool or the RGB Modification tool as well.  If you do, the
          results can be quite confusing.  For example, you might edit
          a color cell, and set its color values to produce a purple.
          However, because of HSV/RGB Modification further down the
          line, the actual color displayed on the image (and in the
          color cell) is yellow.  Very confusing, indeed.


        SSSSeeeeccccttttiiiioooonnnn 5555....3333:::: TTTThhhheeee HHHHSSSSVVVV MMMMooooddddiiiiffffiiiiccccaaaattttiiiioooonnnn TTTToooooooollll
          There are four separate controls in the HSV Modification
          tool.  At the top of the window are a pair of circular
          controls that handle hue remapping.  Lower down is a
          circular control that maps 'white' (and greys) to a
          specified color.  There is a dial control that lets you
          saturate/desaturate the colors of the current information.
          Finally, at the bottom there is a graph window that lets you
          modify intensity values via an arbitrary remapping function.


        SSSSeeeeccccttttiiiioooonnnn 5555....3333....1111:::: HHHHuuuueeee RRRReeeemmmmaaaappppppppiiiinnnngggg CCCCoooonnnnttttrrrroooollllssss
          These two dials are used to define a source and a
          destination range of hue values.  Every hue in the source
          range (defined in the From dial) gets mapped to the value of
          the corresponding point in the destination range (defined in
          the To dial).

          Each dial has a pair of radial lines with handles at their
          ends.  Between the two lines an arc is drawn with an arrow
          at one end.  The wedge drawn by these lines and the arc
          defines a range of values (in degrees).  The direction of
          the arc (clockwise, or counter-clockwise) determines the
          direction of this range of values (increasing or
          decreasing).

          Distributed around the dial are tick marks and the letters
          'R', 'Y', 'G', 'C', 'B', and 'M'.  These letters stand for
          the colors Red, Yellow, Green, Cyan, Blue, and Magenta, and
          they show where these colors appear on the circle.

          The range is shown numerically below the control.  By
          default the range is '330, 30 CW'.  This means that a range
          of values [330, 331, 332, ... 359, 0, 1, ... 28, 29, 30] has
          been defined.  Note that (being a circle) it wraps back to 0
          after 359.

          The range can be changed in many different ways.  You can
          click on the 'handles' at the end of the radial lines and
          move them around.  If you click inside the dial, but not on
          one of the handles, you'll be able to drag the range around
          as a single object.  There are also 5 buttons below the dial



     Page 22                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          that let you rotate the range, flip the direction of the
          range, and increase/decrease the size of the range while
          keeping it centered around the same value.

          In its default state, the To dial is set to the same range
          as the From dial.  When the two dials are set to the same
          range, they are effectively 'turned off', and ignored.

          An example of hue remapping:

          o+  As a simple example of the sort of things you can do with
             the hue remapping control, we'll change the background
             color of the default (_x_v logo) image without changing any
             other colors in the image.  Since the background is
             composed of a gradient of 64 colors, you would not want
             to do this with the Colormap Editing tool.  It would take
             forever.

          o+  First, get the default image up on the screen by running
             'xv' without giving any filenames.  Open up the _x_v _c_o_l_o_r
             _e_d_i_t_o_r window via the CCCCoooollllEEEEddddiiiitttt command.

          o+  Next, click the mouse in the image window and drag it
             around.  You'll see that all the background pixels have
             the same Hue component value (240).

          o+  To remap this hue, simply adjust the From dial so that
             its range includes this Hue value.  The background should
             change from 'blue' to a reddish color, assuming the To
             dial is still set to its default range (centered around
             'R').  If more than the background changed color, you can
             shrink the From range so that it covers fewer colors.  In
             fact, it's possible to shrink the range to the point
             where it only covers only a single value.

          Note that the values printed when you are tracking pixel
          values in the image are the values before the HSV
          Modification tool is applied.  For example, the background
          of the default image will still claim to be blue, regardless
          of what color you may have changed it to.  This is so that
          you know what Hue value you will need to remap if you want
          to change its color again.

          If you press the Reset button that is located near the hue
          remapping controls, it will effectively disable the hue
          remapping by setting the To range equal to the From range.

          Below the hue remapping controls are a group of 'radio
          buttons'.  You can have up to six different hue remappings
          happening simultaneously.  Higher numbered mappings take
          precedence over lower number mappings.




     Page 23                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          An example of multiple hue remappings:

          o+  Draw a From range that is a complete circle.  The easiest
             way to do this is to draw a range that is nearly a full
             circle, then click and hold down the 'increase range'
             button located below the From range dial until the range
             stops getting bigger.

          o+  Copy this range to the To range by pressing the Reset
             button.

          o+  Rotate the To range slightly, by either clicking and
             dragging anywhere in the To range dial, or by using the
             'rotate clockwise' and 'rotate counter-clockwise' buttons
             located below the To range.

          o+  You've just built yourself what is effectively a tint
             control.

          o+  Now, suppose, you'd like to adjust the background color
             of your (tint-modified) image, without affecting anything
             else.  Clicking on the background in the image window
             reveals that the background still has an (original) hue
             of 240.  To modify this hue without affecting anything
             else, we'll need a second hue remapping.

          o+  Click on the 2 radio button.  The dials will change to
             some other default setting.  As before, set the From
             range to encompass the value 240, preferably as 'tightly'
             as possible, and set the To range to produce the desired
             background color.

          Note that the six hue remappings are not 'cascaded'.  The
          output of one remapping is not fed as input into any of the
          other hue remappings.  The hue remappings always operate on
          the hue values in the original image.  In this example, if
          remapping #1 adds 32 to all hue values, thereby mapping the
          blue background (value 240) into a purple-blue (value 272),
          remapping #2 still sees the background at 240, and can remap
          it to anything it likes.  Similarly, in the same example, if
          remapping #1 has mapped a green-blue color (value 208) into
          blue (value 240), remapping #2 will not map this into
          another color.  As far as remapping #2 is concerned, that
          green-blue is still green-blue.

          If it seems complicated, I'm sorry.  It is.


        SSSSeeeeccccttttiiiioooonnnn 5555....3333....2222:::: TTTThhhheeee WWWWhhhhiiiitttteeee RRRReeeemmmmaaaappppppppiiiinnnngggg CCCCoooonnnnttttrrrroooollll
          In the HSV colorspace, 'white' (including black, and all the
          greys in between) has no Hue or Saturation components.  As
          such, it is not possible to use the hue remapping controls



     Page 24                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          to change the color of white pixels in the image, since they
          have no 'color' to change.

          The white remapping control provides a way to add Hue and
          Saturation components to all the whites in the image.  It
          consists of a movable point in a color dial.  The angle of
          the dot from the center of the dial determines the Hue
          component.  The distance of the dot from the center of the
          dial determines the Saturation component.  The further the
          dot is from the center of the dial, the more saturated the
          color will be.

          You can control the white remapping control in several ways.
          You can click on the handle and drag it around with the
          mouse.  There are also four buttons provided under the dial.
          One pair allows you to rotate the handle clockwise and
          counter-clockwise without changing its distance from the
          center.  The other pair of buttons lets you change the
          distance between the handle and the center without changing
          the angle.

          The current Hue and Saturation values provided by the
          control is displayed below the dial.  The first number is
          the Hue component, in degrees, and the second is the
          Saturation component, as a percentage.

          There is also a checkbox that will let you turn off the
          white remapping control.  This lets you quickly compare your
          modified 'white' with the original white.  You can also
          effectively disable the white remapping control by putting
          the handle back in the center of the control.  The easiest
          way to do this is to click and hold the 'move towards
          center' button until the saturation gets down to 0%.

          Example:

          o+  Press the Grey control in the Colormap Editing tool.
             This turns all the colors in the image into shades of
             grey.

          o+  Drag the handle in the white remapping control halfway
             down towards the 'R' mark.  The Hue and Saturation values
             should be roughly 0-degrees and 50%.  The image should
             now be displayed in shades of pink.


        SSSSeeeeccccttttiiiioooonnnn 5555....3333....3333:::: TTTThhhheeee SSSSaaaattttuuuurrrraaaattttiiiioooonnnn CCCCoooonnnnttttrrrroooollll
          The saturation control lets you globally increase or
          decrease the color saturation of the image.  In effect, it
          is much like the 'color' control on most color televisions.

          The saturation control is a dial that operates exactly like



     Page 25                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          the dials described in "Section 5.2.1 Using the Dial
          Controls".  In short, you can click and hold down any of the
          four buttons in the bottom of the control to increase or
          decrease the control's value.  You can also click on the
          dial itself and move the pointer around directly.

          The saturation control has values that range from '-100%' to
          '+100%'.  At its default setting of '0%', the saturation
          control has no effect on the image.  As the values increase,
          the colors become more saturated, up to '+100%' where every
          color is fully saturated.  Likewise, as values decrease, the
          colors become desaturated.  At '-100%', every color will
          become a completely desaturated (i.e., a shade of grey).
          Note that this control is applied after the the White
          Remapping control, so if you 'greyify' the image by
          completely desaturating it, you will not be able to color it
          using the White Remapping control.

          Unless you're trying for some special effects, the useful
          range of this control is probably '+/-20%'.  Also note that
          the control will have no effect on shades of grey, as they
          have no color to saturate.


        SSSSeeeeccccttttiiiioooonnnn 5555....3333....4444:::: TTTThhhheeee IIIInnnntttteeeennnnssssiiiittttyyyy GGGGrrrraaaapppphhhh
          The intensity graph allows you to change the brightness of
          the image, change the contrast of the image, and get some
          unique effects.

          The intensity graph is a function that lets you remap
          intensity values (the Value component in HSV Colorspace)
          into other intensity values.  The input and output values of
          this function both range from 0 to 255.  The input values
          range along the x axis of this graph (the horizontal).  For
          every input value (point along the x axis) there is a unique
          output value determined by the height of the graph at that
          point.  In the graph's default state, the function is a
          straight line from bottom-left to top-right.  In this case,
          each input value produces an equivalent output value, and
          the graph has no effect.

          There are a number of 'handles' along the graph.  These
          provide your major means of interacting with the graph.  You
          can move them around arbitrarily, subject to these two
          constraints: the handles at the far left and far right of
          the graph can only be moved vertically, and handles must
          remain between their neighboring handles for the graph to
          remain a proper function.

          The handles are normally connected by a spline curve.  To
          see this, move one of the handles by clicking and dragging
          it.  (Note that the _x,_y position of the current handle is



     Page 26                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          displayed while the mouse button is held down.)  The
          function will remain a smoothly curved line that passes
          through all the handles.  You can change this behavior by
          putting the function into 'lines' mode.  Press the 'lines'
          button (the second button down from the top).  The function
          will change to a series of line segments that connect the
          handles.  Press the 'spline' button (the top button) to go
          back to 'spline' mode.

          The next two buttons let you add or delete handles.  The
          'add handle' button will insert a handle into the largest
          'gap' in the function.  The 'delete handle' button will
          remove a handle from the smallest 'gap' in the function.
          You can have as little as 2 handles, or as many as 16.  Note
          that as the number of handles gets large, the spline will
          start getting out of control.  You may wish to switch to
          'lines' mode in this case.

          The 'Reset' button puts everything back on a straight line
          connecting bottom-left to top-right (a 1:1 function).  It
          does not change the number of handles, nor does it change
          the x-positions of the handles.

          The 'Gam' button lets you set the function curve by entering
          a single number.  The function is set equal to the gamma
          function:

               Y = 255 * (I/255) ^ (1/g)

          where I is the input value (0-255), g is the gamma value,
          and Y is the computed result.

          Gamma values (for our purposes) can range between 0 and
          10000, non-inclusive.

          o+  A gamma value of '1.00' results in the normal 1:1
             straight line.

          o+  Gamma values of less than 1.00 but greater than 0.00
             result in 'exponential' curves, which will dim the image.

          o+  Gamma values greater than 1.00 result in 'logarithmic'
             curves, which will brighten the image.  Try it and see.

          There is a shortcut for the 'Gam' button.  Type 'g' while
          the mouse is inside the graph window.

          Also, touching any of the handles after a 'Gam' command will
          put the graph back into its 'normal' mode.  (Either 'spline'
          or 'lines' depending on which of the top two buttons is
          turned on.)




     Page 27                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          Generally, whenever you move a graph handle and let go of
          it, the image will be redrawn to show you the effects of
          what you've done.  This can be time-consuming if you intend
          to move many points around.  You can temporarily prevent the
          redisplay of the image by holding down a <shift> key.
          Continue to hold the <shift> key down while you move the
          handles to the new position.  Release the <shift> key when
          you're done, and the image will be redisplayed.


        SSSSeeeeccccttttiiiioooonnnn 5555....4444:::: TTTThhhheeee RRRRGGGGBBBB MMMMooooddddiiiiffffiiiiccccaaaattttiiiioooonnnn TTTToooooooollll
          The RGB Modification tool is a collection of three graph
          windows, each of which operate on one of the components of
          the RGB colorspace.  This tool lets you perform global
          color-correction on the image by boosting or cutting the
          values of one or more of the RGB color components.  You can
          use this to correct for color screens that are 'too blue',
          or for color printers that produce 'brownish' output, or
          whatever.

          The graphs work exactly as explained in "Section 5.3.4:  The
          Intensity Graph".

          Neat Trick: In addition to color-correction, you can use the
          RGB modification tool to add color to images that didn't
          have color to begin with.  For instance, you can 'pseudo-
          color' a greyscale image.

          An example of pseudo-coloring:

          o+  Adjust the Red graph so that there is a strong red
             presence on the right side of the graph, and none on the
             left, or in the middle.

          o+  Adjust the Green graph so that there is a strong green
             presence in the middle of the graph, and none on the left
             or right.

          o+  Adjust the Blue graph so that there is a strong blue
             presence on the left side of the graph, and none on the
             left, or in the middle.

          You now have a transformation that will take greyscale
          images and display them in pseudo-color, using a
          'temperature' color scheme.  Neato!


        SSSSeeeeccccttttiiiioooonnnn 5555....5555:::: TTTThhhheeee CCCCoooolllloooorrrr EEEEddddiiiittttoooorrrr CCCCoooonnnnttttrrrroooollllssss
          These buttons provide general control over the whole _x_v
          _c_o_l_o_r _e_d_i_t_o_r window.  You can display the image with or
          without color modification, save and recall presets, and
          undo/redo changes.  Also, convenience controls are given for



     Page 28                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          performing some of the most common operations on the
          Intensity graph.


          AAAAppppppppllllyyyy  (Keyboard equivalent 'p')
               Displays the image using the current HSV and RGB
               Modifications.  Also turns the 'Display with HSV/RGB
               mods' checkbox on.  (See below.)

               This is only useful when the 'Auto-apply HSV/RGB mods'
               checkbox is off.


          NNNNooooMMMMoooodddd
               Displays the image without any HSV or RGB
               Modifications.  Also turns the 'Display with HSV/RGB
               mods' checkbox off.


          RRRReeeesssseeeetttt  (Keyboard equivalent 'R')
               Resets all HSV and RGB controls to their default
               settings.  Doesn't affect the Colormap Editing tool.


          UUUUnnnnddddoooo Undoes the last change to the HSV or RGB controls.

               It may be helpful to think of _x_v as maintaining a
               series of 32 'snapshots' of the HSV and RGB controls.
               You are normally looking at the last frame in this
               series.  The UUUUnnnnddddoooo control moves you backwards in the
               series.


          RRRReeeeddddoooo Only available after you've hit Undo.  Moves you
               forward in the 'snapshot' series described above.  Note
               that if you have hit UUUUnnnnddddoooo a few times (i.e., you're now
               looking at some frame in the middle of the series), and
               you change an HSV or RGB control, all subsequent frames
               in the series are thrown away, and the current state
               becomes that last frame in the series.


          1111,,,,2222,,,,3333,,,,4444
               Pressing any of these buttons recalls a preset (a
               complete set of values for the HSV and RGB controls).


          SSSSeeeetttt  Used in conjunction with the RRRReeeesssseeeetttt,,,,1111,,,,2222,,,,3333,,,,4444 buttons to
               store the current settings of the HSV and RGB controls
               into a preset.  To do so, press the SSSSeeeetttt button, and
               then press one of the RRRReeeesssseeeetttt,,,,1111,,,,2222,,,,3333,,,,4444 buttons.  The
               current HSV and RGB control settings will be stored in



     Page 29                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



               that preset, as long as _x_v continues running.  The
               values will be lost when the program exits.  It is also
               possible to save these values permanently.  See the
               CCCCuuuuttttRRRReeeessss button (below) and "Section 9: Modifying XV
               Behavior" for more details.


          CCCCuuuuttttRRRReeeessss
               Copies the current settings of the HSV and RGB
               controls, as text, into the X server's cut buffer.  You
               can then use a text editor to paste these values into
               your '.Xdefaults' (or '.Xresources') file.  This lets
               you save the current settings 'permanently'.  See
               "Section 9: Modifying XV Behavior" for more details.


          CCCClllloooosssseeee
               This button closes the _x_v _c_o_l_o_r _e_d_i_t_o_r window.


          BBBBrrrriiiitttteeee
               Brightens the image by moving all the handles in the
               Intensity graph up by a constant amount.


          DDDDiiiimmmm  Darkens the image by moving all the handles in the
               Intensity graph down by a constant amount.


          SSSShhhhaaaarrrrpppp
               Increases the contrast of the image by moving handles
               on the left side of the Intensity graph down, and
               handles on the right side up.


          DDDDuuuullllllll Decreases the contrast of the image by moving handles
               on the left side of the Intensity graph up, and handles
               on the right side down.


          NNNNoooorrrrmmmm  (Keyboard equivalent 'N')
               Normalizes the image so that the darkest pixels in the
               image are given an intensity of '0', and the brightest
               pixels in the image are given an intensity of '255'.
               Intermediate colors are interpolated accordingly.  This
               forces the image to have the full (maximum) dynamic
               range.


          HHHHiiiissssttttEEEEQQQQ  (Keyboard equivalent 'H')
               Runs a histogram equalization algorithm on the
               currently displayed region of the image.  This is, if



     Page 30                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



               you're cropped, it will only run the algorithm on the
               cropped section.  Note, however, that the only
               modification it makes to the image is to generate a
               bizarre corrective Intensity curve.  As such, if you
               HHHHiiiissssttttEEEEQQQQ a section of the image, then UUUUnnnnCCCCrrrroooopppp, the rest of
               the image will probably not be what you'd want.  Also
               note that the histogram curve will 'go away' if you
               touch any of the handles in the Intensity graph window,
               just like a 'gamma' curve would.


          The 'Display with HSV/RGB mods' checkbox tells you whether
          or you're looking at a modified image (checked) or the
          'raw', unmodified image (unchecked).  The AAAAppppppppllllyyyy and NNNNooooMMMMoooodddd
          buttons change the setting of this checkbox, and you can
          also change the checkbox directly by clicking on it.

          The 'Auto-apply HSV/RGB mods' checkbox controls whether or
          not the program regenerates and redisplays the image after
          each change to an HSV or RGB control.  By default, this
          checkbox is turned on, so that you can easily see the
          results of your modifications.  However, in the case that
          you want to make a large number of changes at once, it might
          be preferable to turn automatic redisplay off for a while,
          to speed things up.

          The 'Auto-reset on new image' checkbox controls whether or
          not the HSV and RGB controls are RRRReeeesssseeeetttt back to their default
          values whenever a new image is loaded up.  By default, this
          is also turned on, as when you're playing with the HSV/RGB
          controls, you probably only want to affect the current
          image, and not all subsequently loaded images as well.


     SSSSEEEECCCCTTTTIIIIOOOONNNN 6666:::: TTTTHHHHEEEE LLLLOOOOAAAADDDD WWWWIIIINNNNDDDDOOOOWWWW
          The _x_v _l_o_a_d window lets you load and view images
          interactively, without specifying them on the command line
          when you start _x_v.

          The load window shows the contents of the current directory
          in a scrolling window.  The files will be sorted
          alphabetically, with all the directories (and symbolic links
          to directories, if your operating system supports them)
          displayed first.

          This list window operates in the same way that the one in
          the _x_v controls window works.  (See "Section 3.7.1:
          Operating a List Window" for details.)  In short, you can
          operate the scroll bar, drag the highlight bar around the
          window, and use the up-arrow, down-arrow, Home, End, Page
          Up, and Page Down keys on your keyboard.




     Page 31                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          Whenever you click on a name in the list (or otherwise
          change the position of the highlight bar), the name of the
          highlighted file is copied to the "Load file" text entry
          region, located below the list window.  Pressing the Ok
          button (or typing <return>) will cause the program to
          attempt to load the specified file.  If the load attempt is
          successful, the load window will disappear, and the new
          image will be displayed.  Otherwise, an error message will
          be displayed, and the load window will remain visible.

          The BBBBrrrroooowwwwsssseeee checkbox overrides this behavior, and keeps the
          load window visible until it is explicitly closed via the
          CCCCaaaannnncccceeeellll button.  This is handy if you're using _x_v to 'wander
          around a directory tree', and plan to be using the LLLLooooaaaadddd
          command quite often.

          If the image is successfully loaded, its name will be added
          to the _x_v _c_o_n_t_r_o_l_s window list.  This will let you quickly
          reload it later without have to go through the _x_v _l_o_a_d
          window again.

          You can also load a file by double-clicking on its name in
          the file list.

          If the specified filename begins with a '!' or '|'
          character, the filename will be interpeted as a shell
          command to run.  The leading '!' or '|' gets stripped off,
          and the rest of the line is fed to the default system shell.
          The command is expected to generate an image in one of the
          formats that _x_v recognizes.  This image is expected to be
          the stdout of the specified command.  If the command returns
          non-zero, it is assumed that the command failed, and no
          image is loaded.  You can pipe multiple commands together.
          For example, loading "! xwd | xwdtopnm" would run _x_w_d to
          generate a window dump, pipe that to _x_w_d_t_o_p_n_m to convert it
          to a PPM file, which in turn is piped to _x_v.

          If the specified file is a directory, _x_v will figure that
          out and (instead of loading it) will 'cd' to that directory,
          and display its contents in the list window.

          Above the list window is a pop-up menu button, much like the
          DDDDiiiissssppppllllaaaayyyy MMMMooooddddeeeessss button in the _x_v _c_o_n_t_r_o_l_s window.  It normally
          displays the name of the current directory.  If you click
          this button, and hold the mouse down, the complete path will
          be shown, one directory per line.  You can go 'up' the
          directory tree any number of levels, all the way up to the
          root directory, by simply selecting a directory name in this
          list.

          For those who prefer the direct approach, you can simply
          type file or directory names in the "Load file" text entry



     Page 32                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          region.  If you type a directory name and hit <return>, _x_v
          will 'cd' to that directory and display its contents in the
          list window.  If you type a file name and hit <return>, _x_v
          will attempt to load the file.  You can enter relative paths
          (relative to the currently displayed directory), absolute
          paths, and even paths that begin with a '~'.

          The "Load file" text entry region supports a number of
          emacs-like editing keys.

               Ctrl-F    moves the cursor forward one character

               Ctrl-B    moves the cursor backward one character

               Ctrl-A    moves the cursor to the beginning of the line

               Ctrl-E    moves the cursor to the end of the line

               Ctrl-D    deletes the character to the right of the
               cursor

               Ctrl-U    clears the entire line

               Ctrl-K    clears from the cursor position to the end of
               the line.

          If the filename is so long that it cannot be completely
          displayed in the text entry region, a thick line will appear
          on the left or right side (or both sides) of the region to
          show that "there's more over this way".

          Pressing the RRRReeeessssccccaaaannnn button will rescan the current
          directory.  While the contents of the current directory are
          read each time the load window is opened, it is perfectly
          possible (given a multitasking operating system) that some
          other program may add, delete, or rename files in the
          current directory.  _X_V would not know if this happened.  The
          RRRReeeessssccccaaaannnn button gives you an easy way of 'kicking' _x_v into
          looking again.


     SSSSEEEECCCCTTTTIIIIOOOONNNN 7777:::: TTTTHHHHEEEE SSSSAAAAVVVVEEEE WWWWIIIINNNNDDDDOOOOWWWW
          The _x_v _s_a_v_e window lets you write images back to disk,
          presumably after you've modified them.  You can write images
          back many different formats, not just the original format.
          WWWWaaaarrrrnnnniiiinnnngggg!!!!  Images are saved as they are currently shown (at
          the current size, with the current color modification,
          rotation, cropping, etc. applied).  The only exception to
          this rule is if you are on a 1-bit B/W display.  The fact
          that images have to be stippled in black and white in order
          to be displayed on such a screen doesn't count as
          'modification', and the file won't be saved 'as displayed'.



     Page 33                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          You can manipulate and save full-color images on such a
          display, even if you can't really see them.

          For the most part, the _x_v _s_a_v_e window operates exactly like
          the _x_v _l_o_a_d window.  (See "Section 6: The Load Window" for
          details.)  Only the differences are listed here.

          When the window is opened, it should have the filename of
          the currently loaded file already entered into the text
          entry region.  If you change directories, or click on a file
          name in the list window, this name will be cleared and
          replaced with the new name.

          At the bottom of the window are a list of possible formats
          in which you can save the file.  If you click on one of
          these formats, and your filename has a recognized suffix
          (i.e., '.gif', '.GIF', '.pbm', etc.), the suffix portion of
          your filename will be replaced with the new, appropriate
          suffix for the selected format.

          You can pipe output from _x_v to other programs by using the
          _x_v _s_a_v_e window.  If the first character of the specified
          filename is '!' or '|', the rest of the filename is
          interpreted as a command to pipe the output to, in the
          currently selected image format.  A fine use for this
          feature is directly printing images to a PostScript printer
          by selecting 'PostScript' in the formats list, and typing
          something like "| lpr" as the filename.  In this case, _x_v
          will create a temporary file, write the PostScript to that
          file, and cat the contents of that file to the entered
          command.  _X_V will wait for the command to complete.  If the
          command completed successfully, the _x_v _s_a_v_e window will
          disappear.  If the command was unsuccessful, the window will
          remain visible.  In any event, the temporary file will be
          deleted.

          There is a 'Save at normal size' checkbox.  Normally, when
          you save an image, it will be saved at the current expansion
          (ie, one screen pixel will map to one image pixel in the
          saved file. Sometimes, however, it is desirable to save an
          image at its original size.  This is most relevant when
          you're viewing images larger than your screen.  By default,
          _x_v will automatically shrink images so that they fit on the
          screen.  If you save these images, you'll find that you've
          lost a lot of data, that maybe you wanted to keep.  That's
          what this checkbox is here for.  Note:  certain operations,
          such as SSSSmmmmooooooootttthhhh and DDDDiiiitttthhhheeeerrrr only affect the displayed image.
          If you choose to save an image at its normal size, these
          effects will not be in the saved image.

          At the bottom right side of the window there is a list of
          possible 'Color' variations to save.  Most file formats



     Page 34                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          support different 'sub-formats' for 24-bit color, 8-bit
          greyscale, 1-bit B/W stippled, etc.  Not all of them do.
          Likewise, not all 'Color' choices are available in all
          formats.

          In general, the 'Color' choices do the following:


          FFFFuuuullllllll CCCCoooolllloooorrrr
               Saves the image as currently shown with all color
               modifications, cropping, rotation, flipping, resizing,
               and smoothing.  The image will be saved with all of its
               colors, even if you weren't able to display them all on
               your screen.  For example, you can load a color image
               on a 1-bit B/W display, modify it, and write it back.
               The saved image will still be full color, even though
               all you could see on your screen was some B/W-dithered
               nightmare.


          GGGGrrrreeeeyyyyssssccccaaaalllleeee
               Like Full Color, but saves the image in a greyscale
               format.


          BBBB////WWWW DDDDiiiitttthhhheeeerrrreeeedddd
               Like Full Color, but before saving the image _x_v
               generates a 1-bit-per-pixel, black-and-white dithered
               version of the image, and saves that, instead.


          RRRReeeedddduuuucccceeeedddd CCCCoooolllloooorrrr
               Saves the image as currently shown, with all color
               modifications, cropping, rotation, flipping, resizing,
               and smoothing.  The image will be saved as shown on the
               screen, with as many or few colors as _x_v was able to
               use on the display.  The major purpose of this is to
               allow special effects (color reduction) to be saved, in
               conjunction with the '-ncols' command line option.  You
               will probably never need to use this.

          Format notes:


          GGGGIIIIFFFF  While _x_v can read both the GIF87a and GIF89a formats,
               it will only write GIF87a.  This is in keeping with the
               GIF89 specification, which states that if you don't
               need any of the features added in GIF89 (which _x_v
               doesn't), you should continue to write GIF87, for
               greater compatibility with old GIF87-only readers.

               Since GIF only supports one format (up to 8 bits per



     Page 35                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



               pixel, with a colormap), there will be no size
               difference between a Full Color and a Greyscale image.
               A B/W Dithered image, on the other hand, will be
               considerably smaller.


          PPPPMMMM   Full Color images are saved in the 3-plane, 1-band,
               PM_C format.  Greyscale and B/W Dithered images are
               both saved in the 1-plane, 1-band, PM_C format.  As
               such, there is no size advantage to saving in the B/W
               Dithered format.


          PPPPBBBBMMMM ((((rrrraaaawwww))))
               Full Color images are saved in PPM format.  Greyscale
               images are saved in PGM format.  B/W Dithered images
               are saved in PBM format.  Each of these formats are
               tailored to the data that they save, so PPM images are
               larger than PGM images, which are in turn larger than
               PBM images.

               In the raw variation of the PBM formats, the header
               information is written in plain ASCII text, and the
               image data is written as binary data.  This is the more
               popular of the two dialects of PBM.


          PPPPBBBBMMMM ((((aaaasssscccciiiiiiii))))
               Like PBM (raw), only the image data is written as ASCII
               text.  As such, images written in this format will be
               several times larger than images written in PBM (raw).
               This is a pretty good format for interchange between
               systems because it is easy to parse.  Also, since they
               are pure, printable ASCII text, images saved in this
               format can be mailed, without going through a
               _u_u_e_n_c_o_d_e-like program.

               Note that _x_v-produced PBM files may break some PBM
               readers that do not correctly parse comments.  If your
               PBM reader cannot parse comments, you can easily edit
               the PBM file and remove the comment lines.  A comment
               is everything from a "#" character to the end of the
               line.


          XXXX11111111 BBBBiiiittttmmmmaaaapppp
               Saves files in the format used by the _b_i_t_m_a_p program,
               which is part of the standard X11 distribution.  Since
               bitmap files are inherently 1-bit per pixel, you can
               only select the B/W Dithered option for this format.





     Page 36                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          SSSSuuuunnnn RRRRaaaasssstttteeeerrrrffffiiiilllleeee
               Full/Reduced Color images are stored in a 24-bit RGB
               format, Greyscale images are stored in an 8-bit
               greyscale format, and B/W Dithered images are stored in
               a 1-bit B/W format.


          PPPPoooossssttttSSSSccccrrrriiiipppptttt
               Full/Reduced Color images are stored in a 24-bit RGB
               format, Greyscale images are stored in an 8-bit
               greyscale format, and B/W Dithered images are stored in
               a 1-bit B/W format.

               _X_V writes Encapsulated PostScript, so you can
               incorporate _x_v-generated PostScript into many desktop-
               publishing programs.  _X_V also prepends some color-to-
               greyscale code, so even if your printer doesn't support
               color, you can still print 'color' PostScript images.
               These images will be three times larger (in file size)
               than their greyscale counterparts, so it's a good idea
               to save Greyscale PostScript, unless you know you may
               be printing the file on a color printer at some point.

               Also, you should probably never need to generate B/W
               Dithered PostScript, as every PostScript printer I've
               ever heard of can print greyscale images.  The only
               valid cases I can think of are: A) doing it for a
               special effect, and B) doing it to generate a much
               smaller (roughly 1/8th the size) PostScript file.

               Note: When you try to save a PostScript file, the _x_v
               _p_o_s_t_s_c_r_i_p_t window will pop up to let you specify how
               you want the image printed.  (See "Section 8: The
               PostScript Window", for details.)


          JJJJPPPPEEEEGGGG _X_V writes files in the JFIF format created by the
               Independent JPEG Group.  Full/Reduced Color images are
               written in a 24-bit RGB format, and Greyscale images
               are written in an 8-bit greyscale format.  B/W Dithered
               images should not be used, as they will probably wind
               up being larger than Greyscale versions of the same
               images, due to the way JPEG works.  Note:  You cannot
               write Reduced Color JPEG files.  If you attempt to, a
               Full Color JPEG file will be saved.

               When you save in the JPEG format, a dialog box will pop
               up and ask you for a quality setting.  '75%' is the
               default value, and really, it's a fine value.  You
               shouldn't have to change it unless you're specifically
               trying to trade off quality for compression, or vice
               versa.  The useful range of values is 5%-95%.



     Page 37                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          TTTTIIIIFFFFFFFF Full/Reduced Color images are written in a 24-bit RGB
               format, Greyscale images are written in an 8-bit
               greyscale format, and B/W Dithered images are written
               in a 1-bit B/W format.

               When you save in the TIFF format, a dialog box will pop
               up and ask you which type of image compression it
               should use.  NNNNoooonnnneeee, LLLLZZZZWWWW, and PPPPaaaacccckkkkBBBBiiiittttssss compression types
               are available for Full/Reduced Color, Greyscale, and
               B/W Dithered modes.  In addition, there are two B/W
               Dithered-only algorithms, CCCCCCCCIIIITTTTTTTT GGGGrrrroooouuuupppp3333 and CCCCCCCCIIIITTTTTTTT
               GGGGrrrroooouuuupppp4444.


     SSSSEEEECCCCTTTTIIIIOOOONNNN 8888:::: TTTTHHHHEEEE PPPPOOOOSSSSTTTTSSSSCCCCRRRRIIIIPPPPTTTT WWWWIIIINNNNDDDDOOOOWWWW
          The _x_v _p_o_s_t_s_c_r_i_p_t window lets you describe how your image
          should look when printed.  You can set the paper size and
          the image size, position the image on the paper, and print
          in 'portrait' or 'landscape' mode.

          The majority of the _x_v _p_o_s_t_s_c_r_i_p_t window is taken up by a
          window that shows a white rectangle (the page) with a black
          rectangle (the image) positioned on it.  You can position
          the image rectangle anywhere on the page.  The only
          constraint is that the center of the image (where the two
          diagonal lines meet) must remain on the page.  Only the
          portion of the image that is on the page will actually be
          printed.

          The image can be (roughly) positioned on the page by
          clicking in the image rectangle and dragging it around.  As
          you move the image, the "Top" and "Left" position displays
          will show the size of the top and left margins (the distance
          between the top-left corner of the page and the top-left
          corner of the image).

          You'll note that you have limited placement resolution with
          the mouse.  If you want to fine-position the image, you can
          use the arrow keys to move the image around.  The arrow keys
          will move the image in .001" increments.  You can hold them
          down, and they will auto-repeat.  You can also hold a
          <shift> key down while using the arrow keys.  This will move
          the image in .01" increments.

          You can change the size of the printed image by adjusting
          the "Width" or "Height" dials.  Normally, the dials are
          locked together, to keep the aspect ratio of the image
          constant.  You can unlock the dials by turning the off the
          checkbox located below the dials.  As you change the dials,
          the size of the image (when printed) is displayed below, in
          inches and in millimeters.  The current resolution of the
          image is also displayed below.  The "Resolution" numbers



     Page 38                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          tell you how many image pixels will be printed per inch.

          Located below the 'page' rectangle are a set of radio
          buttons that let you specify the current paper size (8.5" x
          11", 8.5" x 14", 11" x 17", A4, B5, 4"x5", and 35mm), and
          orientation (Portrait and Landscape).

          The Center button will center the image on the page.  The
          Maxpect button will make the image as large as possible
          (maintaining half-inch margins on all sides) without
          changing the aspect ratio.

          There are a pair of small buttons located next to the "Left"
          and "Top" displays.  Clicking the "Left" one will cycle
          between displaying the "Left" margin, the "Right" margin,
          and the "Center X" position (the distance from the left edge
          of the paper to the center of the image).

          Clicking the "Top" display's button will cycle between
          displaying the size of the "Top" margin, the size of the
          "Bottom" margin, and the "Center Y" position (the distance
          from the top edge of the paper to the center of the image).

          At the top of the _x_v _p_o_s_t_s_c_r_i_p_t window are a pair of
          checkboxes.  The "preview" checkbox lets you specify whether
          or not to include a b/w preview of the image in the
          PostScript file.  Certain desktop publishing programs may
          make use of such a preview.

          The 'compress' checkbox lets you specify whether or not to
          generate compressed 8-bit PostScript.  This is particularly
          handy if you're generating color PostScript as color
          PostScript files are normally three times larger than their
          greyscale counterparts.  Compression can shrink these color
          PostsScript files by a factor of 4:1.  It has a lesser
          effect on greyscale images.  It should be noted, however,
          that compressed PostScript files may take 2-3 times longer
          to print than uncompressed PostScript files. However, if you
          are connected to your laser printer via a slow 9600 baud
          serial line, the decreased transmission time due to
          compressed data may more than make up for the increased
          execution time.  You'll have to decide for yourself.

          Click the "Ok" button when you're finished with the _x_v
          _p_o_s_t_s_c_r_i_p_t window.  If everything is successful, the _x_v
          _p_o_s_t_s_c_r_i_p_t and the _x_v _s_a_v_e window will both close.  If _x_v
          was unable to write the PostScript file, the _x_v _p_o_s_t_s_c_r_i_p_t
          window will close, but the _x_v _s_a_v_e window will remain open,
          to give you a chance to enter a different filename.


     SSSSEEEECCCCTTTTIIIIOOOONNNN 9999:::: MMMMOOOODDDDIIIIFFFFYYYYIIIINNNNGGGG XXXXVVVV BBBBEEEEHHHHAAAAVVVVIIIIOOOORRRR



     PPPPaaaaggggeeee 33339999                                         ((((pppprrrriiiinnnntttteeeedddd 3333////11116666////99994444))))






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          _X_V supports literally dozens of command line options and X11
          resources.  Fortunately, it is doubtful that you'll ever
          need to use more than a small few.  The rest are provided
          mainly for that 'one special case' application of _x_v...


        SSSSeeeeccccttttiiiioooonnnn 9999....1111:::: CCCCoooommmmmmmmaaaannnndddd LLLLiiiinnnneeee OOOOppppttttiiiioooonnnnssss OOOOvvvveeeerrrrvvvviiiieeeewwww
          If you start _x_v with the command 'xv -help', the current
          list of options will be displayed:

               xv [-] [-2xlimit] [-aspect _w:_h] [-bg _c_o_l_o_r] [-black
               _c_o_l_o_r]
               [-bw _w_i_d_t_h] [-cegeometry _g_e_o_m] [-cemap] [-cgeometry
               _g_e_o_m]
               [-clear] [-cmap] [-cursor _c_h_a_r#] [-DEBUG _l_e_v_e_l]
               [-display _d_i_s_p] [-dither] [-expand _e_x_p] [-fg _c_o_l_o_r]
               [-fixed] [-geometry _g_e_o_m] [-help] [-hi _c_o_l_o_r] [-hsv]
               [-igeometry _g_e_o_m] [-imap] [-keeparound] [-lo _c_o_l_o_r] [-
               max]
               [-maxpect] [-mono] [-ncols _n_c] [-nglobal] [-ninstall]
               [-nopos] [-noqcheck] [-owncmap] [-perfect] [-quit] [-
               rbg _c_o_l_o_r]
               [-rfg _c_o_l_o_r] [-rgb] [-rmode _m_o_d_e] [-_r_o_o_t] [-_r_w] [-
               _s_l_o_w_2_4]
               [-_s_m_o_o_t_h] [-_v_i_s_u_a_l _t_y_p_e] [-_w_a_i_t _s_e_c_o_n_d_s] [-_w_h_i_t_e _c_o_l_o_r]
               [-_w_l_o_o_p] [-_n_o_r_e_s_e_t_r_o_o_t] [-_b_r_o_w_s_e] [-_n_o_s_t_a_t] [-_b_e_s_t_2_4]
               [-_q_u_i_c_k_2_4]
               [-_c_e_c_m_a_p] [-_c_r_o_p] [-_r_v] [-_n_o_l_i_m_i_t_s] [-_l_o_a_d_c_l_e_a_r]
               [_f_i_l_e_n_a_m_e ...]


        SSSSeeeeccccttttiiiioooonnnn 9999....2222:::: GGGGeeeennnneeeerrrraaaallll OOOOppppttttiiiioooonnnnssss
          -help
               Print usage instructions, listing the current available
               command-line options.  Any unrecognized option will do
               this as well.


          -display _d_i_s_p
               Specifies the display that _x_v should attempt to connect
               to.  If you don't specify a display, _x_v will use the
               environment variable $_D_I_S_P_L_A_Y.


          -fg _c_o_l_o_r  (Resource name: foreground _s_t_r_i_n_g)
               Sets the foreground color used by the windows.


          -bg _c_o_l_o_r  (Resource name: background _s_t_r_i_n_g)
               Sets the background color used by the windows.





     Page 40                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          -hi _c_o_l_o_r  (Resource name: highlight _s_t_r_i_n_g)
               Sets the highlight color used for the top-left edges of
               the control buttons.


          -lo _c_o_l_o_r  (Resource name: lowlight _s_t_r_i_n_g)
               Sets the lowlight color used for the bottom-right edges
               of the control buttons, and also the background of some
               windows.


          -bw _b_w_i_d_t_h  (Resource name: borderWidth _i_n_t_e_g_e_r)
               Sets the width of the border on the windows.  Your
               window manager may choose to ignore this, however.


        SSSSeeeeccccttttiiiioooonnnn 9999....3333:::: IIIImmmmaaaaggggeeee SSSSiiiizzzziiiinnnngggg OOOOppppttttiiiioooonnnnssss
          -geometry _g_e_o_m  (Resource name: geometry _s_t_r_i_n_g)
               Lets you specify the size and placement of the 'image'
               window.  It's most useful when you only specify a
               position, and let _x_v choose the size.  If you specify a
               size as well, _x_v will create a window of that size,
               unless -fixed is specified.  The geom argument is in
               the form of a normal X geometry string (e.g. "300x240"
               or "+10+10" or "400x300+10+10").


          -fixed  (Resource name: fixed _b_o_o_l_e_a_n)
               Only used in conjunction with the -geometry option.  If
               you specify a window size with the -geometry option, _x_v
               will normally stretch the picture to exactly that size.
               This is not always desirable, as it may seriously
               distort the aspect ratio of the picture.  Specifying
               the -fixed option corrects this behavior by instructing
               _x_v to use the specified geometry size as a maximum
               window size.  It will, however, preserve the original
               aspect ratio of the picture.

               For example, if you give a rectangular geometry of
               '320x240', and you try to display a square picture with
               a size of '256x256', the window opened will actually be
               '240x240', which is the largest square that still fits
               in the '320x240' rectangle that was specified.


          -expand _e_x_p  (Resource name: expand  _f_l_o_a_t_i_n_g-_p_o_i_n_t)
               Lets you specify an initial expansion or compression
               factor for the picture.  You can specify floating-point
               values.  Values larger than zero multiply the picture's
               dimensions by the given factor.  (i.e., an expand
               factor of '3' will make a 320x200 image display as
               960x600).



     Page 41                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



               Factors less than zero are treated as reciprocals.
               (i.e., an expand factor of '-4' makes the picture 1/4th
               its normal size.).  '0' is not a valid expansion
               factor.


          -aspect _w:_h  (Resource name: aspect _s_t_r_i_n_g)
               Lets you set an initial aspect ratio, and also sets the
               value used by the AAAAssssppppeeeecccctttt control.  The aspect ratio of
               nearly every X display (and, in fact, any civilized
               graphics display) is 1:1.  What this means is that
               pixels appear to be 'square'.  A 100 pixel wide by 100
               pixel high box will appear on the screen as a square.
               Unfortunately, this is not the case with some screens
               and digitizers.  The -aspect option lets you stretch
               the picture so that the picture appears correctly on
               your display.  Unlike the other size-related options,
               this one doesn't care what the size of the overall
               picture is.  It operates on a pixel-by-pixel basis,
               stretching each image pixel slightly, in either width
               or height, depending on the ratio.

               Aspect ratios greater than '1:1' (e.g., '4:3') make the
               picture wider than normal.  Aspect ratios less than
               '1:1' (e.g. '2:3') make the picture taller than normal.
               (Useful aspect ratio: A 512x480 image that was supposed
               to fill a standard 4x3 video screen (produced by many
               video digitizers) should be displayed with an aspect
               ratio of '5:4')


        SSSSeeeeccccttttiiiioooonnnn 9999....4444:::: CCCCoooolllloooorrrr AAAAllllllllooooccccaaaattttiiiioooonnnn OOOOppppttttiiiioooonnnnssss
          -ncols _n_c  (Resource name: ncols _i_n_t_e_g_e_r)
               Sets the maximum number of colors that _x_v will use.
               Normally, this is set to 'as many as it can get'.
               However, you can set this to smaller values for
               interesting effect.  Most notably, if you set it to
               '0', it will display the picture by dithering with
               'black' and 'white'.  (The actual colors used can be
               set by the -black and -white options, below.)


          -nglobal (Resource name: nglobal _b_o_o_l_e_a_n)
               Adjusts the way the program behaves when it is unable
               to get all the colors it requested.  Normally, it will
               search the display's default colormap, and 'borrow' any
               colors it deems appropriate.  These borrowed colors
               are, however, not owned by _x_v, and as such, can changed
               without _x_v'_s permission, or knowledge.  If this
               happens, the displayed picture will change, in a less-
               than-desirable direction.  If you specify the -nglobal
               option, _x_v will not use 'global' colors.  It will only



     Page 42                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



               use colors that it successfully allocated, which makes
               it immune to any color changes.

               It should be noted that 'use global colors' is the
               default because color changes aren't generally a
               problem if you are only using _x_v to display a picture
               for a short time.  Color changes only really become a
               problem if you use _x_v to display a picture that you
               will be keeping around for a while, while you go and do
               some other work (such as using _x_v to display a
               background).  In such cases you will want to specify
               -nglobal.  Note: using the -ncols or -root options
               automatically turn on -nglobal.


          -rw  (Resource name: rwColor _b_o_o_l_e_a_n)
               Tells _x_v to use read/write color cells.  Normally, _x_v
               allocates colors read-only, which allows it to share
               colors with other programs.  If you use read/write
               color cells, no other program can use the colors that
               _x_v is using, and vice-versa.  The only reason you'd do
               such a thing is that using read/write color cells
               allows the Apply function in the _x_v _c_o_l_o_r _e_d_i_t_o_r window
               to operate much faster.


          -perfect  (Resource name: perfect _b_o_o_l_e_a_n)
               Makes _x_v try 'extra hard' to get all the colors it
               wants.  In particular, when -perfect is specified, _x_v
               will allocate and install its own colormap if (and only
               if) it was unable to allocate all the desired colors.
               This option is not allowed in conjunction with the
               -root option.


          -owncmap  (Resource name: ownCmap _b_o_o_l_e_a_n)
               Like '-perfect', only this option forces _x_v to always
               allocate and install its own colormap, thereby leaving
               the default colormap untouched.


          -cecmap  (Resource name: ceditColorMap _b_o_o_l_e_a_n)
               Specifies whether _x_v installs the image's colormap in
               the _x_v _c_o_l_o_r _e_d_i_t_o_r window, as well as in the image's
               window.  By default, the program does install the
               colormap in the color editor window, however this can
               occasionally make the color editor window unreadable.
               (This option only apples when the '-perfect' or '-
               owncmap' options create their own colormaps.)


          -ninstall  (Resource name: ninstall _b_o_o_l_e_a_n)



     Page 43                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



               Prevents _x_v from 'installing' its own colormap, when
               the -perfect or -owncmap options are in effect.
               Instead of installing the colormap, it will merely 'ask
               the window manager, nicely' to take care of it.  This
               is the correct way to install a colormap (i.e., ask the
               WM to do it), unfortunately, it doesn't actually seem
               to work in many window managers, so the default
               behavior is for _x_v to handle installation itself.
               However, this has been seen to annoy one window manager
               (_d_x_w_m), so this option is provided if your WM doesn't
               like programs installing their own colormaps.


        SSSSeeeeccccttttiiiioooonnnn 9999....5555:::: 22224444----bbbbiiiitttt CCCCoooonnnnvvvveeeerrrrssssiiiioooonnnn OOOOppppttttiiiioooonnnnssss
          The following options only come into play if you are using
          _x_v to display 24-bit RGB data (PPM files, color PM files,
          JPEG files, the output of _b_g_g_e_n, etc.).  They have no effect
          whatsoever on how GIF pictures or 8-bit greyscale images are
          displayed.


          -quick24  (Resource name: quick24 _b_o_o_l_e_a_n)
               Forces _x_v to use the 'quick' 24-bit to 8-bit conversion
               algorithm.  This algorithm dithers the picture using a
               fixed set of colors that span the entire RGB
               colorspace.  In versions of _x_v prior to 2.10, this was
               the default algorithm.  It no longer is.


          -slow24  (Resource name: slow24 _b_o_o_l_e_a_n)
               Specifies that the 'slow' 24-bit to 8-bit conversion
               algorithm is to be used by the program.  This algorithm
               uses a version of Heckbert's median cut algorithm to
               pick the 'best' colors on a per-image basis, and
               dithers with those.  This is the current default
               conversion algorithm.

               Advantages: The -slow24 algorithm often produces better
               looking pictures than the -quick24 algorithm.

               Disadvantages: The -slow24 algorithm is about half the
               speed of the -quick24 algorithm.  Also, since the
               colors are chosen on a per-image basis, it can't be
               used to display multiple images simultaneously, as each
               image will almost certainly want a different set of 256
               colors.  The -quick24 algorithm, however, uses the same
               exact colors for all images, so it can display many
               images simultaneously, without running out of colors.


          -best24  (Resource name: best24 _b_o_o_l_e_a_n)
               Forces _x_v to use the same algorithm used in the program



     Page 44                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



               _p_p_m_q_u_a_n_t, written by Jef Poskanzer.  This algorithm
               also uses a version of Heckbert's median cut algorithm,
               but is capable of picking 'better' colors than the
               -slow24 algorithm, and it _d_o_e_s_n'_t dither.

               Advantages:  Generally produces slightly better images
               than the -slow24 algorithm.  Also, the images are
               undithered, so they look better when expanded.

               Disadvantages:  _M_u_c_h slower than the -slow24 algorithm.
               Like, 5 to 10 times slower.  The images produced aren't
               _t_h_a_t much better than those produced by the -slow24
               algorithm.


          -noqcheck  (Resource name: noqcheck _b_o_o_l_e_a_n)
               Turns off a 'quick check' that is normally made.
               Normally, before running either of the 24-bit to 8-bit
               conversion algorithms, _x_v determines whether the
               picture to be displayed has more than 256 unique colors
               in it.  If the picture doesn't, it will treat the
               picture as an 8-bit colormapped image (i.e., GIF), and
               won't run either of the conversion algorithms.

               Advantages: The pictures will be displayed 'perfectly',
               whereas if they went through either of the conversion
               algorithms, they'd be dithered.

               Disadvantages: Often uses a lot of colors, which limits
               the ability to view multiple images at once.  (See the
               -slow24 option above for further info about color
               sharing.)


        SSSSeeeeccccttttiiiioooonnnn 9999....6666:::: RRRRooooooootttt WWWWiiiinnnnddddoooowwww OOOOppppttttiiiioooonnnnssss
          _x_v has the ability to display images on the root window of
          an X display, rather than opening its own window (the
          default behavior).  When using the root window, the program
          is somewhat limited, because the program cannot receive
          input events (key press and mouse clicks) from the root
          window.  As a result, you cannot track pixel values, or
          crop, nor can you use keyboard commands while the mouse is
          in the root window.


          -root  (Resource name:  <none>)
               Directs _x_v to display images in the root window,
               instead of opening its own window.  Exactly how the
               images will be displayed in the root window is
               determined by the setting of the -rmode option.





     Page 45                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          -rmode _m_o_d_e    (Resource name: rootMode _i_n_t_e_g_e_r)
               Determines how images are to be displayed on the root
               window, when -root has been specified.  You can find
               the current list of 'modes' by using a mode value of
               '-1'.  _X_V will complain, and show a list of valid
               modes.  The current list at of the time of this writing
               is:

                    0:   tiling
                    1:   integer tiling
                    2:   mirrored tiling
                    3:   integer mirrored tiling
                    4:   centered tiling
                    5:   centered on a solid background
                    6:   centered on a 'warp' background
                    7:   centered on a 'brick' background

               The default mode is '0'.  See "Section 3.5: The Display
               Modes Menu" for a description of the different display
               modes.


          -noresetroot (Resource name: resetroot)
               Normally, when changing from root to window display
               mode, the root is set to the standard X crosshatch
               pattern.  Using -noresetroot or setting resetroot to
               false will force the root to remain.  This is useful
               when comparing between different tiled images.


          -rfg _c_o_l_o_r  (Resource name: rootForeground _s_t_r_i_n_g)
               Sets the 'foreground' color used in some of the root
               display modes.


          -rbg _c_o_l_o_r  (Resource name: rootBackground _s_t_r_i_n_g)
               Sets the 'background' color used in some of the root
               display modes.


          -max  (Resource name: <none>)
               Makes _x_v automatically stretch the image to the full
               size of the screen.  This is mostly useful when you
               want _x_v to display a background.  While you could just
               as well specify the dimensions of your display ('-geom
               1152x900' for example), the -max option is display-
               independent.  If you suddenly decide to start working
               on a 1280x1024 display (ferinstance) the same command
               will still work.  Note: If you specify -max when you
               aren't using -root, the behavior is slightly different.
               The image will be made as large as possible while still
               preserving the normal aspect ratio.



     Page 46                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          -maxpect  (Resource name: <none>)
               Makes the image as large as possible while preserving
               the aspect ratio.


          -quit  (Resource name: <none>)
               Makes _x_v display the (first) specified file and exit,
               without any user intervention.  Since images displayed
               on the root window remain there until explicitly
               cleared, this is very useful for having _x_v display
               background images on the root window in some sort of
               start-up script.  Needless to say, this is only useful
               if you are using -root.


          -clear  (Resource name: <none>)
               Clears the root window of any extraneous _x_v images.
               Note: it is not necessary to do an 'xv -clear' before
               displaying another picture in the root window.  _x_v will
               detect that there's an old image in the root window and
               automatically clear it out (and free the associated
               colors).


        SSSSeeeeccccttttiiiioooonnnn 9999....7777:::: WWWWiiiinnnnddddoooowwww OOOOppppttttiiiioooonnnnssss
          _X_V currently consists of three main windows, plus one window
          for the actual image.  These three windows (the _x_v _c_o_n_t_r_o_l_s
          window, the _x_v _i_n_f_o window, and the _x_v _c_o_l_o_r _e_d_i_t_o_r window)
          may be automatically mapped and positioned when the program
          starts.


          -cmap  (Resource name: ctrlMap _b_o_o_l_e_a_n)
               Maps the _x_v _c_o_n_t_r_o_l_s window.


          -cgeom _g_e_o_m  (Resource name: ctrlGeometry _s_t_r_i_n_g)
               Sets the initial geometry of the _x_v _c_o_n_t_r_o_l_s window.
               Note: only the position information is used.  The
               window is of fixed size.


          -imap  (Resource name: infoMap _b_o_o_l_e_a_n)
               Maps the _x_v _i_n_f_o window.


          -igeom _g_e_o_m  (Resource name: infoGeometry _s_t_r_i_n_g)
               Sets the initial geometry of the _x_v _i_n_f_o window.  Note:
               only the position information is used.  The window is
               of fixed size.





     Page 47                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          -cemap  (Resource name: ceditMap _b_o_o_l_e_a_n)
               Maps the _x_v _c_o_l_o_r _e_d_i_t_o_r window.


          -cegeom _g_e_o_m  (Resource name: ceditGeometry _s_t_r_i_n_g)
               Sets the initial geometry of the _x_v _c_o_l_o_r _e_d_i_t_o_r
               window.  Note: only the position information is used.
               The window is of fixed size.


          -nopos  (Resource name: nopos _b_o_o_l_e_a_n)
               Turns off the 'default' positioning of the various _x_v
               windows.  Every time you open a window, you will be
               asked to position it.  (Assuming your window manager
               asks you such things.  _m_w_m, for instance doesn't seem
               to ask)


        SSSSeeeeccccttttiiiioooonnnn 9999....8888:::: MMMMiiiisssscccceeeellllllllaaaannnneeeeoooouuuussss OOOOppppttttiiiioooonnnnssss
          -mono  (Resource name: mono _b_o_o_l_e_a_n)
               Forces the image to be displayed as a greyscale.  This
               is most useful when you are using certain greyscale X
               displays.  While _x_v attempts to determine if it's
               running on a greyscale display, many X displays lie,
               and claim to be able to do color.  (This is often
               because they have color graphics boards hooked up to
               b/w monitors.  The computer, of course, has no way of
               knowing what type of monitor is attached.)  On these
               displays, if you don't specify -mono, what you will see
               is a greyscale representation of one of the RGB outputs
               of the system.  (For example, you'll see the 'red'
               output on our greyscale Sun 3/60s.) The -mono option
               corrects this behavior.


          -white _c_o_l_o_r  (Resource name: white _s_t_r_i_n_g)
               Specifies the 'white' color used when the picture is
               b/w stippled.  (When '-ncols 0' has been specified.)


          -black _c_o_l_o_r  (Resource name: black _s_t_r_i_n_g)
               Specifies the 'black' color used when the picture is
               b/w stippled.  (When '-ncols 0' has been specified.)

               Try something like: 'xv -ncols 0 -bl red -wh yellow
               <filename>' for some interesting, late-'60s-style
               psychodelia effects.


          -wait _s_e_c_s  (Resource name: <none>)
               Turns on a 'slide-show' feature.  Normally, if you
               specify multiple input files, _x_v will display the first



     Page 48                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



               one, and wait for you to give the NNNNeeeexxxxtttt command (or
               whatever).  The -wait option makes _x_v wait the
               specified number of seconds, and then go on to the next
               picture, without any user intervention.  The program
               still accepts commands, so it's possible to 'abort' the
               current picture without waiting the full specified time
               by using the NNNNeeeexxxxtttt command.


          -wloop  (Resource name: <none>)
               Normally, when running a slide-show with the -wait
               option, _x_v will terminate after displaying the last
               image.  If you also specify the -wloop option, the
               program will loop back to the first image and continue
               the slide-show until the user issues the Quit command.


          -rgb  (Resource name: hsvMode _b_o_o_l_e_a_n)
               Specifies that, by default, the colormap editing dials
               in the _x_v _c_o_l_o_r _e_d_i_t_o_r window should be in RGB mode.
               This is the normal default behavior.


          -hsv  (Resource name: hsvMode _b_o_o_l_e_a_n)
               Specifies that, by default, the colormap editing dials
               in the _x_v _c_o_l_o_r _e_d_i_t_o_r window should be in HSV mode.


          -dither  (Resouce name: autoDither _b_o_o_l_e_a_n)
               When specified, tells _x_v to automatically issue a
               DDDDiiiitttthhhheeeerrrr command whenever an image is first displayed.
               Useful on displays with limited color capabilities (4-
               bit and 6-bit displays.)


          -smooth  (Resource name:  autoSmooth _b_o_o_l_e_a_n)
               When specified, tells _x_v to automatically issue a
               SSSSmmmmooooooootttthhhh command whenever an image is first displayed.
               This is useful when you are using one of the image
               sizing options (such as '-expand' or '-max').


          -crop  (Resource name: autoCrop _b_o_o_l_e_a_n)
               When specified, tells _x_v to automatically issue an
               AAAAuuuuttttooooCCCCrrrroooopppp command whenever an image is first displayed.


          -visual _v_i_s_t_y_p_e  (Resource name: visual _s_t_r_i_n_g)
               Normally, _x_v uses the default visual model provided by
               your X server.  You can override this by explicitly
               selecting a visual to use.  Valid types are _S_t_a_t_i_c_G_r_a_y,
               _S_t_a_t_i_c_C_o_l_o_r, _T_r_u_e_C_o_l_o_r, _G_r_a_y_S_c_a_l_e, _P_s_e_u_d_o_C_o_l_o_r,



     Page 49                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



                and _D_i_r_e_c_t_C_o_l_o_r.  Not all of these are necessarily
               provided on any given X display.  Run _x_d_p_y_i_n_f_o on your
               display to find out what visual types are supported.


          -cursor _c_u_r_s  (Resource name: cursor _i_n_t_e_g_e_r)
               Specifies an alternate cursor to use in the image
               window (instead of the normal 'cross' cursor).  curs
               values are obtained by finding the character number of
               a cursor you like in the 'cursor' font.  (Run 'xfd -fn
               cursor' to display the cursor font.)  For example, a
               curs value of '56' corresponds to the (singularly
               useless) 'Gumby' cursor.


          -keeparound  (Resource name: keepAround _b_o_o_l_e_a_n)
               The '-keeparound' option is now poorly named, as I've
               changed the default behavior.  Now, if you DDDDeeeelllleeeetttteeee the
               last file in the _x_v _c_o_n_t_r_o_l_s list, nothing unexpected
               will happen.  If you specify the '-keeparound' option,
               which toggles the '-keeparound' flag off, the program
               will automatically exit as a convenience.  It should
               probably be renamed '-goaway' or something...


          -2xlimit  (Resource name: 2xlimit _b_o_o_l_e_a_n)
               By default, _x_v prevents the image window from ever
               getting larger than the screen.  Unfortunately, because
               of this, if you load an image that is larger than your
               screen, the image will be shrunk until it fits on your
               screen.  Some folks find this undesirable behavior.
               Specifying the -2xlimit option doubles the size
               limitations.  The image window will be kept from
               getting larger than 2x the width and height of your
               screen.

               Just in case you're wondering why there's any size
               limitations: it's fairly easy to accidentally ask for a
               huge image to be generated.  Simply crop a section of
               the image, zoom so you can see the individual pixels,
               and uncrop.  If there were no size limitations, the
               (expanded many times) image could be huge, and might
               crash your X server.  At the very least, it would take
               a long period of time, and freeze your X server during
               part of it.  Generally undesirable behavior.


          -nolimits  (Resource name: nolimites  _b_o_o_l_e_a_n)
               For the truly daring, this turns off all limitations on
               the maximum size of an image window.  (Well, there's
               still an X-imposed maximum size of 64k by 64k, but that
               really shouldn't be a problem.) Warning:  as mentioned



     Page 50                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



               above, it is fairly easy to accidentally generate a
               huge image when you do an UUUUnnnnCCCCrrrroooopppp command, and you may
               well crash _x_v, your X server, the host machine, or all
               three.  Use At Your Own Risk!!!


          -rv  (Resource name: reverse)
               Makes _x_v display a 'negative' of the loaded image.
               White becomes black, and black becomes white.  Color
               images will have 'interesting' effects, as the RGB
               components are individually reversed.  For example, _r_e_d
               (255,0,0) will become _c_y_a_n (0,255,255), _y_e_l_l_o_w will
               become _b_l_u_e, and so on.


          -DEBUG _l_e_v_e_l  (Resource name: <none>)
               Turns on some debugging information.  You shouldn't
               need this.  If everything worked perfectly, I wouldn't
               need this either.


          -browse  (Resource name: browseMode _b_o_o_l_e_a_n)
               Prevents the _x_v _l_o_a_d window from being closed whenever
               you successfully load a file.  This makes 'browsing' a
               directory somewhat more pleasant.


          -nostat  (Resource name: nostat _b_o_o_l_e_a_n)
               Turns off the stat() call is is performed for each file
               whenever you change directories in the _x_v _l_o_a_d and _x_v
               _s_a_v_e windows.  This is useful if you're on a machine
               with lots of remote files mounted on it, and you find
               the directory switching to be too slow.


          -loadclear  (Resource name: clearOnLoad _b_o_o_l_e_a_n)
               If you were on a PseudoColor display, _x_v used to
               automatically clear the image window (or the root
               window, if you were in a root mode), whenever you
               loaded a new image.  This was to prevent the
               potentially annoying/confusing 'rainbow' effect that
               happens when colormap entries are freed and reallocated
               with different colors.  Ths has changed.  By default,
               _x_v no longer clears the image/root window.  This is for
               two reasons:  I've decided that the rainbow effect is
               semi-entertaining, in that it gives you something to
               look at while the next image is being loaded.
               Secondly, if you are viewing a series of images that
               have the same colors in them, it's possible for _x_v to
               animate them (by using the '-wait' command line
               option), albeit no faster than one frame every 1-2
               seconds.  For example, you can go get the satellite



     Page 51                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



               radar images from vmd.cso.uiuc.edu (in the directory
               'wx'), run 'xv -wait 0 -wloop SA*', and voila!  Just
               like the evening news!


          -    Specifying '-' all by itself tells _x_v to take its input
               from stdin, rather than from a file.  This lets you put
               _x_v on the end of a Un*x pipe.


        SSSSeeeeccccttttiiiioooonnnn 9999....9999:::: CCCCoooolllloooorrrr EEEEddddiiiittttoooorrrr RRRReeeessssoooouuuurrrrcccceeeessss
          You can set default values for all of the HSV and RGB
          modification controls in the _x_v _c_o_l_o_r _e_d_i_t_o_r window via X
          resources.  The easiest way to explain this is with an
          example.


          o+  Start _x_v and put it in the background by typing 'xv &'.

          o+  Type the command 'cat >foo' in an active _x_t_e_r_m window

          o+  Bring the _x_v _c_o_l_o_r _e_d_i_t_o_r window up.

          o+  Issue the CCCCuuuutttt RRRReeeessssoooouuuurrrrcccceeeessss command.

          o+  Click your _M_i_d_d_l_e mouse button in the _x_t_e_r_m window.  A
             set of resource lines describing the current state of the
             _x_v _c_o_l_o_r _e_d_i_t_o_r controls will be 'pasted' into the
             window.

          o+  You could type '<ctrl-D>' in the _x_t_e_r_m to complete the
             cat command, edit this file, and put it in your
             .Xdefaults/.Xresources file.


          The lines generated by CCCCuuuutttt RRRReeeessssoooouuuurrrrcccceeeessss will look like the
          following:
          xv.default.huemap1: 330  30  CW 330  30  CW
          xv.default.huemap2:  30  90  CW  30  90  CW
          xv.default.huemap3:  90 150  CW  90 150  CW
          xv.default.huemap4: 150 210  CW 150 210  CW
          xv.default.huemap5: 210 270  CW 210 270  CW
          xv.default.huemap6: 270 330  CW 270 330  CW
          xv.default.whtmap:  0 0 1
          xv.default.satval:  0
          xv.default.igraf: S 4 : 0,0 : 64,64 : 192,192 : 254,254
          xv.default.rgraf: S 4 : 0,0 : 64,64 : 192,192 : 254,254
          xv.default.ggraf: S 4 : 0,0 : 64,64 : 192,192 : 254,254
          xv.default.bgraf: S 4 : 0,0 : 64,64 : 192,192 : 254,254

          These lines completely describe one state of the _x_v _c_o_l_o_r
          _e_d_i_t_o_r controls.  There are five different states that you



     Page 52                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          can specify via X resources.  The 'default' state (as shown)
          holds the settings used whenever the program is first
          started, and whenever the Reset command is used.  You can
          also store settings in one of the four _x_v presets (accessed
          via the '1'-'4' buttons in the _x_v _c_o_l_o_r _e_d_i_t_o_r) by changing
          the string 'default' in the above lines to 'preset1',
          'preset2', 'preset3', or 'preset4' respectively.

          There are four types of resource described in these lines:
          huemap, whtmap, satval, and graf.


        SSSSeeeeccccttttiiiioooonnnn 9999....9999....1111:::: HHHHuuuueeeemmmmaaaapppp RRRReeeessssoooouuuurrrrcccceeeessss
          The huemap resources describe the state of the hue remapping
          dials.  There are six huemap resources per state of the _x_v
          _c_o_l_o_r _e_d_i_t_o_r.  These huemap resources are numbered
          'huemap1', 'huemap2', ...  'huemap6', and correspond to the
          '1'-'6' radio buttons under the hue remapping dials.

          Each huemap resources takes six parameters:

          1. The 'starting' angle of the From range, in degrees
             (integer).

          2. The 'ending' angle of the From range, in degrees
             (integer).

          3. The direction of the From range.  Either 'cw' (clockwise)
             or 'ccw' (counter-clockwise).

          4. The 'starting' angle of the To range, in degrees
             (integer).

          5. The 'ending' angle of the To range, in degrees (integer).

          6. The direction of the To range.  Either 'cw' or 'ccw'.


        SSSSeeeeccccttttiiiioooonnnn 9999....9999....2222:::: WWWWhhhhttttmmmmaaaapppp RRRReeeessssoooouuuurrrrcccceeeessss
          The whtmap resource describes the state of the white
          remapping control.  There is one whtmap resource per state
          of the _x_v _c_o_l_o_r _e_d_i_t_o_r controls.  The whtmap resource takes
          three parameters:

          1. The hue to remap 'white' to, in degrees (integer).

          2. The saturation to give to the remapped 'white', in
             percent (integer).

          3. A boolean specifying whether the white remapping control
             is enabled.  If '1', the control is enabled.  If '0', the
             control is disabled.



     Page 53                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



        SSSSeeeeccccttttiiiioooonnnn 9999....9999....3333:::: SSSSaaaattttvvvvaaaallll RRRReeeessssoooouuuurrrrcccceeee
          The satval resource describes the value of the Saturation
          dial.  There is one satval resource per state.  The satval
          resource takes a single integer value, in the range +/-100,
          which specifies how much to add or subtract to overall image
          color saturation.


        SSSSeeeeccccttttiiiioooonnnn 9999....9999....4444:::: GGGGrrrraaaaffff RRRReeeessssoooouuuurrrrcccceeeessss
          The graf resources describe the state of the four 'graph'
          windows in the _x_v _c_o_l_o_r _e_d_i_t_o_r window (Intensity, Red,
          Green, and Blue).  The graf resources can be in one of two
          formats, 'gamma' and 'spline/line'.

          In 'gamma' format, the graf resource takes two parameters:

          1. The letter 'G', specifying 'gamma' mode

          2. A single floating point number specifying the gamma
             value.


          In 'spline/line' mode, the graf resource takes a variable
          number of parameters:

          1. The letter 'S' specifying 'spline' mode, or the letter
             'L' specifying 'line' mode.

          2. An integer number indicating the number of handles
             (control points) that this graph window will have.  (Must
             be in the range 2-16, inclusive.)

          3. For each handle, there will be a ':', and the x and y
             positions of the handle, separated by a comma.  The x and
             y positions can be in the range 0-255 inclusive.


        SSSSeeeeccccttttiiiioooonnnn 9999....9999....5555:::: OOOOtttthhhheeeerrrr RRRReeeessssoooouuuurrrrcccceeeessss
          Also, there are the boolean resources 'autoApply',
          'displayMods', and 'autoReset', which control the initial
          settings of the three checkboxes in the _x_v _c_o_l_o_r _e_d_i_t_o_r
          window.

          There are also boolean resources 'saveNormal', 'pspreview',
          and 'pscompress' which control the initial settings of the
          checkboxes in the _x_v _s_a_v_e and _x_v _p_o_s_t_s_c_r_i_p_t windows.


     LLLLIIIIMMMMIIIITTTTAAAATTTTIIIIOOOONNNNSSSS
          _x_v will NOT work on displays that aren't 1-, 2-, 4-, 6-, 8-,
          16- 24-, or 32-bits deep.  Luckily, that should still cover
          nearly every display out there.  It may not work on certain



     Page 54                                         (printed 3/16/94)






     xxxxvvvv((((llll))))               RRRReeeevvvv:::: 2222....11110000 ((((FFFFeeeebbbb 22226666,,,, 1111999999992222))))                xxxxvvvv((((llll))))



          6- or 24-bit displays.

          It also only displays the first image in GIF files that have
          multiple images in them.

          As for PM pictures, this program only displays 1-plane PM_I
          pictures, or 1-, 3-, or 4-plane PM_C pictures.

     PPPPMMMM FFFFOOOORRRRMMMMAAAATTTT
          The PM format is a file format that we use at the GRASP Lab
          for our image processing work.  If you aren't at Penn, you
          are unlikely to ever run into a PM-format file, so don't
          worry about it.  Please ignore all references to PM.

          The 4-, 6-, 16-, 24-, and 32-bit code has not been
          extensively tested.  (A 4-bit MicroVax GPX system, a 6-bit
          HP 9000/320, a 16-bit Sony 3710, and a 24-bit HP 9000/350,
          respectively.  The 32-bit code hasn't actually been tested
          at all.) You won't be able to do '----nnnnccccoooollllssss 0' on a 6-, 16-,
          24-, or 32-bit display, not that you should want to.

     AAAAUUUUTTTTHHHHOOOORRRRSSSS
          John Bradley  -  [e-mail]

          GIF reading code based on gif2ras.c, by Patrick J. Naughton
          ([e-mail])

          GIF writing code essentially unchanged from code written by
          Michael Maudlin ([e-mail]).

          SUN Rasterfile i/o code written by Dave Heath
          ([e-mail])

          JPEG interface code written by Markus Baur
          ([e-mail])

          JPEG i/o code provided by the Independent JPEG Group.

          TIFF i/o code and interface code written by Sam Leffler
          ([e-mail])

          Portions of 'ppmquant' snarfed for the '-best24' algorithm.
          _p_p_m_q_u_a_n_t (and the rest of the _p_b_m_p_l_u_s package) was written
          by Jef Poskanzer.  ([e-mail])

          fsQuick code written and supplied by David B. Rosen
          ([e-mail]). This code is a very fast implementation
          of Floyd-Steinberg dithering for 1-bit b/w displays.







     Page 55                                         (printed 3/16/94)